DEV Community: Yury Samkevich

Learn OpenGL with Rust: textures

Yury Samkevich — Sun, 04 Sep 2022 23:59:02 +0000

Welcome to the fourth part of Learn OpenGL with Rust tutorial. In the last article we've learned what vertex buffer and vertex array objects are and how to use them and shaders to render simple primitives.

In this article we will explore what textures are, how to load texture from an image file and render it to the screen. All the source code for the article you can find on github by the following link.

Textures

So far we rendered a triangle and even painted it with a different colors. But what if we want to render some more realistic image, let's say Ferris, Rust's unofficial mascot. It would take significant amount of time and resources to recreate image with vertices and specify color attribute for each vertex.

Texture is usually used in computer graphics for that purpose. A texture is generally an image used to add detail to an object. We can insert a lot of detail in an image and give the illusion the object is extremely detailed with no need to add extra vertices. OpenGL can use different type of textures: 1D, 3D, cube textures etc. In this article, we will concern ourselves only with two-dimensional textures.

Like VBOs and VAOs, textures are objects in OpenGL and require a generated id before we can use them. We create a dedicated type for a texture:



pub struct Texture {
    pub id: GLuint,
}

To generate a new texture id we use gl::GenTextures function:



impl Texture {
    pub unsafe fn new() -> Self {
        let mut id: GLuint = 0;
        gl::GenTextures(1, &mut id);
        Self { id }
    }
}

In order to delete texture resources once we don't need them anymore we implement Drop trait for texture type:



impl Drop for Texture {
    fn drop(&mut self) {
        unsafe {
            gl::DeleteTextures(1, [self.id].as_ptr());
        }
    }
}

Just like other objects in OpenGL, textures have to be bind to apply operations to them. Since images are 2D arrays of pixels we use gl::BindTexture function with gl::TEXTURE_2D as the first parameter:



impl Texture {
    pub unsafe fn bind(&self) {
        gl::BindTexture(gl::TEXTURE_2D, self.id)
    }
}

Render a rectangle

In order to draw a texture we first need to learn how to draw a rectangle. We can draw a rectangle using two triangles, because OpenGL mainly works with triangles:

As you can see, some vertices of triangles are overlapped. Imagine if we'd wanted to draw a more complex model with thousands of triangles, there will be large chunks that overlap. What would be a better solution is to store only the unique vertices and then specify the order at which we want to draw these vertices in.

Element buffer objects (EBO) are intended to help us solving the problem. An EBO is a buffer that stores indices that OpenGL uses to decide what vertices to draw. We will reuse our Buffer implementation that we defined in previous lessons with the gl::ELEMENT_ARRAY_BUFFER type.

To get started we first have to specify the vertices and the indices according to the above picture:



type Pos = [f32; 2];

#[repr(C, packed)]
struct Vertex(Pos);

#[rustfmt::skip]
const VERTICES: [Vertex; 4] = [
    Vertex([-0.5, -0.5]),
    Vertex([ 0.5, -0.5]),
    Vertex([ 0.5,  0.5]),
    Vertex([-0.5,  0.5]),
];

#[rustfmt::skip]
const INDICES: [i32; 6] = [
    0, 1, 2,
    2, 3, 0
];

Next we need to create the element buffer object and copy the indices into the buffer:



let index_buffer = Buffer::new(gl::ELEMENT_ARRAY_BUFFER);
index_buffer.set_data(&INDICES, gl::STATIC_DRAW);

The last thing left to do is to replace the gl::DrawArrays call with gl::DrawElements to indicate we want to render the triangles from an index buffer, specifying that we want to draw 6 vertices in total:



gl::DrawElements(gl::TRIANGLES, 6, gl::UNSIGNED_INT, ptr::null());

Texture coordinates

Now when we know how to draw a rectangle let's look how we can use our knowledge to render a texture. First we need to map a texture to the rectangle and tell each vertex of the rectangle which part of the texture it corresponds to. Therefore, each vertex should have a texture coordinate associated with it. These coordinates range from 0.0 to 1.0 where (0,0) is conventionally the bottom-left corner and (1,1) is the top-right corner of the texture image. The new vertex array will now include texture coordinates for each vertex:



type Pos = [f32; 2];
type TextureCoords = [f32; 2];

#[repr(C, packed)]
struct Vertex(Pos, TextureCoords);

#[rustfmt::skip]
const VERTICES: [Vertex; 4] = [
    Vertex([-0.5, -0.5],  [0.0, 1.0]),
    Vertex([ 0.5, -0.5],  [1.0, 1.0]),
    Vertex([ 0.5,  0.5],  [1.0, 0.0]),
    Vertex([-0.5,  0.5],  [0.0, 0.0]),
];

Next we need to alter the vertex shader to accept the texture coordinates as a vertex attribute and then forward the coordinates to the fragment shader:



#version 330
in vec2 position;
in vec2 vertexTexCoord;

out vec2 texCoord;

void main() {
    gl_Position = vec4(position, 0.0, 1.0);
    texCoord = vertexTexCoord;
}

The fragment shader should then accept the texCoord output variable as an input variable:



out vec4 FragColor;

in vec2 texCoord;

uniform sampler2D texture0;

void main() {
    FragColor = texture(texture0, texCoord);
}

The fragment shader declares a uniform sampler2D that we later assign our texture to. To sample the color of a texture we use GLSL's built-in texture function that returns a color of the texture at the texture coordinate.

Load texture data

Now that the texture object has been configured it's time to load the texture image. Texture images can be stored in dozens of file formats, each with their own structure and ordering of data. Likely for us there is a crate image which can handle everything for us, just add it as a dependency in Cargo.toml file.

In order to load texture data we first load an image by the given path. Then we convert the image in a general RGBA format and upload the image data to GPU using gl::TexImage2D:



impl Texture {
    pub unsafe fn load(&self, path: &Path) -> Result<(), ImageError> {
        self.bind();

        let img = image::open(path)?.into_rgba8();
        gl::TexImage2D(
            gl::TEXTURE_2D,
            0,
            gl::RGBA as i32,
            img.width() as i32,
            img.height() as i32,
            0,
            gl::RGBA,
            gl::UNSIGNED_BYTE,
            img.as_bytes().as_ptr() as *const _,
        );
        Ok(())
    }
}

Now, when we put all the pieces together, rendering initialisation code will look like the following:



let vertex_shader = Shader::new(VERTEX_SHADER_SOURCE, gl::VERTEX_SHADER)?;
let fragment_shader = Shader::new(FRAGMENT_SHADER_SOURCE, gl::FRAGMENT_SHADER)?;
let program = ShaderProgram::new(&[vertex_shader, fragment_shader])?;

let vertex_array = VertexArray::new();
vertex_array.bind();

let vertex_buffer = Buffer::new(gl::ARRAY_BUFFER);
vertex_buffer.set_data(&VERTICES, gl::STATIC_DRAW);

let index_buffer = Buffer::new(gl::ELEMENT_ARRAY_BUFFER);
index_buffer.set_data(&INDICES, gl::STATIC_DRAW);

let pos_attrib = program.get_attrib_location("position")?;
set_attribute!(vertex_array, pos_attrib, Vertex::0);
let color_attrib = program.get_attrib_location("vertexTexCoord")?;
set_attribute!(vertex_array, color_attrib, Vertex::1);

let texture = Texture::new();
texture.load(&Path::new("assets/ferris.png"))?;

gl::BlendFunc(gl::SRC_ALPHA, gl::ONE_MINUS_SRC_ALPHA);
gl::Enable(gl::BLEND);

In two last lines we set alpha blending function. This is a topic for another discussion and for now is enough to know that we use it to set the rules how to combine an image with a background.

The code in the rendering loop:



gl::ClearColor(0.5, 0.5, 0.5, 1.0);
gl::Clear(gl::COLOR_BUFFER_BIT);
texture.bind();
program.apply();
vertex_array.bind();
gl::DrawElements(gl::TRIANGLES, 6, gl::UNSIGNED_INT, ptr::null());

If you compile and run the code with cargo run you should see the following image:

Congratulation! You just rendered Ferris!

Texture units

What if we want to use several textures at the same time? You might noticed that we declared uniform sampler2D in the fragment shader. We actually can assign a location value to the texture sampler using that uniform parameter. The location of a texture is more commonly known as a texture unit.

We have to tell OpenGL to which texture unit each shader sampler belongs to by setting each sampler. We add set_int_uniform function for ShaderProgram type:



impl ShaderProgram {
    pub unsafe fn set_int_uniform(&self, name: &str, value: i32) -> Result<(), ShaderError> {
        self.apply();
        let uniform = CString::new(name)?;
        gl::Uniform1i(gl::GetUniformLocation(self.id, uniform.as_ptr()), value);
        Ok(())
    }
}

Now we can load two textures and pass their texture units to the fragment shader:



let texture0 = Texture::new();
texture0.load(&Path::new("assets/logo.png"))?;
program.set_int_uniform("texture0", 0)?;

let texture1 = Texture::new();
texture1.load(&Path::new("assets/rust.jpg"))?;
program.set_int_uniform("texture1", 1)?;

We can activate texture unit using gl::ActiveTexture and passing in the texture unit we'd like to use. For that we add activate function for Texture type:



impl Texture {
    pub unsafe fn activate(&self, unit: GLuint) {
        gl::ActiveTexture(unit);
        self.bind();
    }
}

So we can activate our textures before drawing in a render loop:



texture0.activate(gl::TEXTURE0);
texture1.activate(gl::TEXTURE1);

We also need to edit the fragment shader to accept another sampler:



#version 330
out vec4 FragColor;

in vec2 texCoord;

uniform sampler2D texture0;
uniform sampler2D texture1;

void main() {
    vec4 color0 = texture(texture0, texCoord);
    vec4 color1 = texture(texture1, texCoord);
    FragColor = mix(color0, color1, 0.6) * color0.a;
}

The final output color is now the combination of two textures.

For example the mix of these two textures you can see on the following screenshot:

Summary

Today we've learned what textures are and how to load them from an image file and render to the screen. We've rendered Ferris 🦀 and explored how to use textures in order to create some simple graphic effects.

If you find the article interesting consider hit the like button and subscribe for updates.

Learn OpenGL with Rust: first triangle

Yury Samkevich — Mon, 29 Aug 2022 21:42:05 +0000

Welcome to the third part of Learn OpenGL with Rust tutorial. Last time we've learned how graphics pipeline of modern OpenGL works and how we can use shaders to configure it.

In this article we are going to explore what vertex buffer and vertex array objects are and how we can use them and shaders to render our first triangle. All the source code for the article you can find on github by the following link.

Vertex data

First we have to give OpenGL some input vertex data, before start drawing something on the screen. Usually this data comes in the form of vertex attributes. One of those attributes is a world position of vertex, which determines where the object or shape eventually end up on the screen. Since we are going to draw a simple triangle we will use the following representation of position:

type Pos = [f32; 2];

We use f32 type for each of two position's component: x and y. Once vertex potion will be processed in the vertex shader, it should be in normalized device coordinates and vary between -1.0 and 1.0.

Another attribute is a vertex color. We will represent color as an array of 3 values: the red, green and blue component, commonly abbreviated to RGB. When defining a color we set the strength of each component to a value between 0.0 and 1.0.

type Color = [f32; 3];

Finally we can represent our vertex as a tuple of position and color:

#[repr(C, packed)]
struct Vertex(Pos, Color);

The triangle we are going to draw will consist of 3 vertices positioned at (-0.5, -0.5), (0.5, -0.5) and (0.0, 0.5) in clockwise order with red, green and blue colors accordingly:

#[rustfmt::skip]
const VERTICES: [Vertex; 3] = [
    Vertex([-0.5, -0.5], [1.0, 0.0, 0.0]),
    Vertex([0.5,  -0.5], [0.0, 1.0, 0.0]),
    Vertex([0.0,   0.5], [0.0, 0.0, 1.0])
];

Vertex buffer object

After defining the vertex data we want to send it as an input to the first process of the graphics pipeline: the vertex shader. This could be done by creating memory on the GPU where we store the vertex data and configuring how OpenGL should interpret that memory.

In order to do that we will use vertex buffer objects (VBO) that can store a large number of vertices in the GPU's memory. Sending data to the graphics card from the CPU is relatively slow. Using VBO we can send large batches of data all at once to the graphics card and keep it there.

First we will define struct for buffer object. We will store unique id corresponding to the buffer and target for buffer type. OpenGL has many types of buffer objects and the buffer type of a vertex buffer object is gl::ARRAY_BUFFER.

pub struct Buffer {
    pub id: GLuint,
    target: GLuint,
}

To generate a new buffer id we will use gl::GenBuffers function. The new method for buffer looks like this:

impl Buffer {
    pub unsafe fn new(target: GLuint) -> Self {
        let mut id: GLuint = 0;
        gl::GenBuffers(1, &mut id);
        Self { id, target }
    }
}

Before uploading the actual data into buffer we first have to make it's active by calling gl::BindBuffer:

impl Buffer {
    pub unsafe fn bind(&self) {
        gl::BindBuffer(self.target, self.id);
    }
}

Now we have a buffer object and can make a call to the gl::BufferData function that copies the previously defined vertex data into the buffer's memory:

impl Buffer {
    pub unsafe fn set_data<D>(&self, data: &[D], usage: GLuint) {
        self.bind();
        let (_, data_bytes, _) = data.align_to::<u8>();
        gl::BufferData(
            self.target,
            data_bytes.len() as GLsizeiptr,
            data_bytes.as_ptr() as *const _,
            usage,
        );
    }
}

We declare function set_data which takes slice of vertices data of generic type D. The second parameter specifies how we want the graphics card to manage the given data. It could be one of 3:

gl::STREAM_DRAW: the vertex data is set once and drawn once
gl::STATIC_DRAW: the vertex data is set once and drawn many times (as in our case with triangle)
gl::DYNAMIC_DRAW: the vertex data is changed a lot and drawn many times

Before upload data with gl::BufferData we transform our vertex data, since gl::BufferData receives data as a byte array.

To delete a buffer once we don't need it anymore we implement Drop trait and call gl::DeleteBuffers function with buffer id as an argument:

impl Drop for Buffer {
    fn drop(&mut self) {
        unsafe {
            gl::DeleteBuffers(1, [self.id].as_ptr());
        }
    }
}

Vertex array object

Last time we talked that vertex shaders allow us to specify any input we want in the form of vertex attributes. In order to do that we have to manually specify what part of our input data goes to which vertex attribute in the vertex shader. But before doing that we have to create and bind vertex array object (VAO). After that any vertex attribute configuration will be stored inside a VAO. This makes switching between different vertex data and attribute configurations as easy as binding a different VAO.

The struct for VAO looks similar to VBO:

pub struct VertexArray {
    pub id: GLuint,
}

To generate a new VAO id we use gl::GenVertexArrays:

impl VertexArray {
    pub unsafe fn new() -> Self {
        let mut id: GLuint = 0;
        gl::GenVertexArrays(1, &mut id);
        Self { id }
    }
}

Like for VBO we implement Drop for VertexArray trait to clean up unused resources:

impl Drop for VertexArray {
    fn drop(&mut self) {
        unsafe {
            gl::DeleteVertexArrays(1, [self.id].as_ptr());
        }
    }
}

To use a VAO all you have to do is to bind it using gl::BindVertexArray:

impl VertexArray {
    pub unsafe fn bind(&self) {
        gl::BindVertexArray(self.id);
    }
}

Now we can tell OpenGL how it should interpret the vertex data for each attribute using gl::VertexAttribPointer:

impl VertexArray {
    pub unsafe fn set_attribute<V: Sized>(
        &self,
        attrib_pos: GLuint,
        components: GLint,
        offset: GLint,
    ) {
        self.bind();
        gl::VertexAttribPointer(
            attrib_pos,
            components,
            gl::FLOAT,
            gl::FALSE,
            std::mem::size_of::<V>() as GLint,
            offset as *const _,
        );
        gl::EnableVertexAttribArray(attrib_pos);
    }
}

We define set_attribute with generic type V which represents vertex layout. The first parameter specifies which vertex attribute we want to configure. The next argument specifies the number of components in the vertex attribute. The last parameter is the offset of where the position data begins in the buffer. For simplicity we assume that type of data in a vertex attribute is always f32.

In order to get a vertex attribute location in vertex shader we will modify ShaderProgram from the last article adding the following method:

impl ShaderProgram {
    pub unsafe fn get_attrib_location(&self, attrib: &str) -> Result<GLuint, NulError> {
        let attrib = CString::new(attrib)?;
        Ok(gl::GetAttribLocation(self.id, attrib.as_ptr()) as GLuint)
    }
}

Configuring all this information manually for each of vertex attributes might be tedious and error prone. It would be nice to automatically calculate number of components and a field offset in data type that represents vertex layout knowing a name of the field. For that we are going to use a bit of Rust's macro magic:

#[macro_export]
macro_rules! set_attribute {
    ($vbo:ident, $pos:tt, $t:ident :: $field:tt) => {{
        let dummy = core::mem::MaybeUninit::<$t>::uninit();
        let dummy_ptr = dummy.as_ptr();
        let member_ptr = core::ptr::addr_of!((*dummy_ptr).$field);
        const fn size_of_raw<T>(_: *const T) -> usize {
            core::mem::size_of::<T>()
        }
        let member_offset = member_ptr as i32 - dummy_ptr as i32;
        $vbo.set_attribute::<$t>(
            $pos,
            (size_of_raw(member_ptr) / core::mem::size_of::<f32>()) as i32,
            member_offset,
        )
    }};
}

Now we can use our macro in the following way:

set_attribute!(vertex_array, 0, Vertex::position);

Inside the macro we calculate offset to the field position in type Vertex, size of the field and pass this information to set_attribute function of vertex array.

Rendering a triangle

Finally, we can put everything together to render our first triangle. First we compile our shaders and link them into a program. Then we create a vertex buffer object and upload vertex data for our triangle into it. After that we create vertex array object and configure vertex attributes:

let vertex_shader = Shader::new(VERTEX_SHADER_SOURCE, gl::VERTEX_SHADER)?;
let fragment_shader = Shader::new(FRAGMENT_SHADER_SOURCE, gl::FRAGMENT_SHADER)?;
let program = ShaderProgram::new(&[vertex_shader, fragment_shader])?;
let vertex_buffer = Buffer::new(gl::ARRAY_BUFFER);
vertex_buffer.set_data(&VERTICES, gl::STATIC_DRAW);
let vertex_array = VertexArray::new();
let pos_attrib = program.get_attrib_location("position")?;
set_attribute!(vertex_array, pos_attrib, Vertex::0);
let color_attrib = program.get_attrib_location("color")?;
set_attribute!(vertex_array, color_attrib, Vertex::1);

Now when the vertex data is loaded, shader program is created and the data to the attributes is linked, all that's left is to simply use our program and VAO and call gl::DrawArrays in the main loop:

gl::ClearColor(0.3, 0.3, 0.3, 1.0);
gl::Clear(gl::COLOR_BUFFER_BIT);
self.program.apply();
self.vertex_array.bind();
gl::DrawArrays(gl::TRIANGLES, 0, 3);

The first parameter of gl::DrawArrays specifies the kind of primitive we want to draw, the second parameter specifies the starting index of the vertex array and the last parameter specifies the number of vertices we want to draw.

Now if we run our program with cargo run, we should see the following result:

Congratulations! You just drew your first triangle using OpenGL.

Summary

Today we've learned what vertex buffer and vertex array objects are and how to use them to render simple primitives.

Next time we are going to learn what the texture is and how to draw pictures in OpenGL. Stay tuned!

If you find the article interesting consider hit the like button and subscribe for updates.

Learn OpenGL with Rust: shaders

Yury Samkevich — Sun, 28 Aug 2022 16:18:00 +0000

Welcome to the second part of Learn OpenGL with Rust tutorial. In the last article we learned a bit of OpenGL theory and discovered how to create a window, initialize OpenGL context and call some basic api to clear a window with a color of our choice.

In this article we'll briefly discuss modern OpenGL graphics pipeline and how to configure it using shaders. All the source code for the article you can find on my github.

Graphics pipeline

We consider screen of the devise as a 2D array of pixels, but usually we want to draw objects in 3D space, so a large part of OpenGL's work is about transforming 3D coordinates to 2D pixels that fit on a screen. The process of transforming 3D coordinates to 2D pixels is managed by the graphics pipeline.

The graphics pipeline can be divided into several steps where each step requires the output of the previous step as its input. All of these steps have their own specific function and can be executed in parallel. Each step of the pipeline runs small programs on the GPU called shader.

As input to the graphics pipeline we pass vertices, list of points from which shapes like triangles will be constructed later. Each of these points is stored with certain attributes and it's up to programmer to decide what kind of attributes they want to store. Commonly used attributes are 3D position and color value.

The first part of the pipeline is the vertex shader that takes as input a single vertex. The main purpose of the vertex shader is transformation of 3D coordinates. It also passes important attributes like color and texture coordinates further down the pipeline.

The primitive assembly stage takes as input all the vertices from the vertex shader and assembles all the points into a primitive shape.

The output of the primitive assembly stage is passed to the geometry shader. The geometry shader takes the primitives from the previous stage as input and can either pass a primitive down to the rest of the pipeline, modify it, completely discard or even replace it with other primitives.

After that final list of shapes is composed and converted to screen coordinates, the rasterization stage turns the visible parts of the shapes into pixel-sized fragments.

The main purpose of the fragment shader is to calculate the final color of a pixel. In more advanced scenarios, there could also be calculations related to lighting and shadowing and special effects in this program.

Finally, the end result is composed from all these shape fragments by blending them together and performing depth and stencil testing. So even if a pixel output color is calculated in the fragment shader, the final pixel color could still be something different when rendering multiple triangles one over another.

The graphics pipeline is quite complex and contains many configurable parts. In modern OpenGL we are required to define at least a vertex and fragment shader (geometry shader is optional).

Shaders

As discussed earlier in modern OpenGL, it's up to us to instruct the graphics card what to do with the data. And we can do it writing shader programs. We will configure two very simple shaders to render our first triangle.

Shaders are written in a C-style language called GLSL (OpenGL Shading Language). OpenGL will compile your program from source at runtime and copy it to the graphics card. Below you can find the source code of a vertex shader in GLSL:



#version 330
in vec2 position;
in vec3 color;
out vec3 vertexColor;

void main() {
    gl_Position = vec4(position, 0.0, 1.0);
    vertexColor = color;
}

Each shader begins with a declaration of its version. Since OpenGL 3.3 and higher the version numbers of GLSL match the version of OpenGL.

Next we declare all the input vertex attributes in the vertex shader with the in keyword. We have two vertex attributes: one for vertex position and another one for vertex color. Apart from the regular C types, GLSL has built-in vector and matrix types: vec and mat with a number at the end which stands for number of components. The final position of the vertex is assigned to the special gl_Position variable.

The output from the vertex shader is interpolated over all the pixels on the screen covered by a primitive. These pixels are called fragments and this is what the fragment shader operates on. The fragment shader only requires one output variable and that is a vector of size 4 that defines the final color output, FragColor in our case. Here is an example of our simple fragment shader:



#version 330
out vec4 FragColor;
in vec3 vertexColor;

void main() {
    FragColor = vec4(vertexColor, 1.0);
}

Shader can specify inputs and outputs using in and out keywords. If we want to send data from one shader to another we have to declare an output in the first shader and a similar input in the second shader. OpenGL will link those variables together and send data between shaders. In our case we pass vertexColor from vertex shader to the fragment shader. This value will be interpolated among all the fragments of our triangle.

In order for OpenGL to use the shader it has to dynamically compile it at run-time from a source code. But first we declare shader struct which will store shader object id:



pub struct Shader {
    pub id: GLuint,
}

To create an object we will use gl::CreateShader function which takes type of shader (gl::VERTEX_SHADER or gl::FRAGMENT_SHADER) as a first argument. Then we attach the shader source code to the shader object and compile the shader:



let source_code = CString::new(source_code)?;
let shader = Self {
    id: gl::CreateShader(shader_type),
};
gl::ShaderSource(shader.id, 1, &source_code.as_ptr(), ptr::null());
gl::CompileShader(shader.id);

To check if compilation was successful and to retrieving the compile log we can use gl::GetShaderiv and gl::GetShaderInfoLog accordingly. The final version of shader creation function looks like this:



impl Shader {
    pub unsafe fn new(source_code: &str, shader_type: GLenum) -> Result<Self, ShaderError> {
        let source_code = CString::new(source_code)?;
        let shader = Self {
            id: gl::CreateShader(shader_type),
        };
        gl::ShaderSource(shader.id, 1, &source_code.as_ptr(), ptr::null());
        gl::CompileShader(shader.id);

        // check for shader compilation errors
        let mut success: GLint = 0;
        gl::GetShaderiv(shader.id, gl::COMPILE_STATUS, &mut success);

        if success == 1 {
            Ok(shader)
        } else {
            let mut error_log_size: GLint = 0;
            gl::GetShaderiv(shader.id, gl::INFO_LOG_LENGTH, &mut error_log_size);
            let mut error_log: Vec<u8> = Vec::with_capacity(error_log_size as usize);
            gl::GetShaderInfoLog(
                shader.id,
                error_log_size,
                &mut error_log_size,
                error_log.as_mut_ptr() as *mut _,
            );

            error_log.set_len(error_log_size as usize);
            let log = String::from_utf8(error_log)?;
            Err(ShaderError::CompilationError(log))
        }
    }
}

To delete a shader once we don't need it anymore we implement trait Drop and will call gl::DeleteShader function with shader id as an argument:



impl Drop for Shader {
    fn drop(&mut self) {
        unsafe {
            gl::DeleteShader(self.id);
        }
    }
}

Shader program

So far vertex and fragment shaders have been two separate objects. We will use shader program to link them together. When linking the shaders into a program it links the outputs of each shader to the inputs of the next shader. Hence we can have program linking errors if outputs and inputs do not match.

Similar to Shader we will declare Program struct, which holds program id generated by gl::CreateProgram function. To link all shaders together we need to attach them first with gl::AttachShader and then use gl::LinkProgram for linking. Like with shaders we can check for and retrieve linking errors if we have any.



pub struct ShaderProgram {
    pub id: GLuint,
}

impl ShaderProgram {
    pub unsafe fn new(shaders: &[Shader]) -> Result<Self, ShaderError> {
        let program = Self {
            id: gl::CreateProgram(),
        };

        for shader in shaders {
            gl::AttachShader(program.id, shader.id);
        }

        gl::LinkProgram(program.id);

        let mut success: GLint = 0;
        gl::GetProgramiv(program.id, gl::LINK_STATUS, &mut success);

        if success == 1 {
            Ok(program)
        } else {
            let mut error_log_size: GLint = 0;
            gl::GetProgramiv(program.id, gl::INFO_LOG_LENGTH, &mut error_log_size);
            let mut error_log: Vec<u8> = Vec::with_capacity(error_log_size as usize);
            gl::GetProgramInfoLog(
                program.id,
                error_log_size,
                &mut error_log_size,
                error_log.as_mut_ptr() as *mut _,
            );

            error_log.set_len(error_log_size as usize);
            let log = String::from_utf8(error_log)?;
            Err(ShaderError::LinkingError(log))
        }
    }
}

To prevent resources liking we implement Drop trait for shader program as well:



impl Drop for ShaderProgram {
    fn drop(&mut self) {
        unsafe {
            gl::DeleteProgram(self.id);
        }
    }
}

Finally we can use our declared types to compile shaders and link them into a program, which we will use during rendering:



let vertex_shader = Shader::new(VERTEX_SHADER_SOURCE, gl::VERTEX_SHADER)?;
let fragment_shader = Shader::new(FRAGMENT_SHADER_SOURCE, gl::FRAGMENT_SHADER)?;
let program = ShaderProgram::new(&[vertex_shader, fragment_shader])?;

To use the program while rendering we declare function apply for Program type that uses gl::UseProgram under the hood:



pub unsafe fn apply(&self) {
    gl::UseProgram(self.id);
}

Every rendering call after apply will use this program object.

Summary

Today we've learned how graphics pipeline of modern OpenGL works and how we can use shaders to configure it.

Next time we are going to learn what vertex buffer and vertex array objects are and how we can use knowledge we've got so far to render a first triangle.

If you find the article interesting consider hit the like button and subscribe for updates.

Learn OpenGL with Rust: creating a window

Yury Samkevich — Sun, 21 Aug 2022 10:36:00 +0000

Motivation

Computer graphics is an exciting and enjoyable topic due to its combination of technology, art and creativity. In the past few years we've been seeing a rapid evolution in the field of VR and AR technologies that utilise computer graphics a lot. All this makes the topic of studying graphics APIs more popular than ever.

OpenGL is definitely the simplest graphics API available. There are other APIs one might consider looking at: DirectX, Metal, Vulcan. But all of them ether not cross-platform or much more low-level than OpenGL which makes them challenging to learn.

In this series of articles we are going to learn basics of OpenGL and try our hands on writing some graphics applications. We will use Rust as a programming language. Traditionally graphics programming closely related to С/C++ due to performance constraints. Rust is a modern alternative to C/C++ it's much safer and have good interoperability with C, which we are going to use calling OpenGL API. For this article experience of Rust is not a requirement although prior programming experience is nice to have. Rust book is a great resource to start if you want to learn more about Rust.

All the code for articles you can find on my github. The project will have branches pointed at the state of the code for each article in the series.

In this article we'll explore how to create a window, initialize OpenGL context and call some basic api to clear a window with a desired color.

A bit of OpenGL theory

Before we start our journey we should first define what OpenGL actually is. OpenGL is might be considered as an API that provides a large set of functions that could be used to manipulate graphics and images. However, OpenGL is not an API, but simply a specification, which specifies what the result/output of each function should be and how it should perform. OpenGL specification does't give implementation details, and implementation of library could be different as long as its results comply with the specification.

Usually we can think about an implementation of OpenGL as a large state machine: a collection of variables that define how OpenGL operates. The state of OpenGL is generally referred to as OpenGL context. Often we use OpenGL changing its state by setting some options, manipulating some buffers and then render using the current context.

When we tell OpenGL that we want to clear a buffer with blue color instead of black for example, we change the state of OpenGL by changing some context variable that sets how OpenGL should draw. Once we change the context by telling OpenGL it should clear with blue, the next drawing call will use blue color to fill a buffer by default.

OpenGL was developed with several abstractions in mind. One of those abstractions is object in OpenGL. You can think about object here as a collection of options that represents a subset of OpenGL's state.

Imagine if we want to have an object that represents the settings of the drawing window. It could have the window's size, how many colors it supports and so on. Whenever we want to use objects in OpenGL we frequently will follow the next workflow: first create an object and store its id, then bind the object by id to the target location, set object's options and finally un-bind the object by setting the current object id to 0. An approximate example of how to change windows size might look like following:

// create object
let mut object_id = 0;
gl::GenObject(1, &mut object_id);
// bind/assign object to context
gl::BindObject(gl::WINDOW_TARGET, object_id);
// set options of object currently bound to gl::WINDOW_TARGET
gl::SetObjectOption(gl::WINDOW_TARGET, GL::OPTION_WINDOW_WIDTH,  800);
gl::SetObjectOption(gl::WINDOW_TARGET, GL::OPTION_WINDOW_HEIGHT, 600);
// set context target back to default
gl::BindObject(gl::WINDOW_TARGET, 0);

Now when we learned a bit about OpenGL as a specification and a library and how OpenGL approximately operates under the hood it's time to jump into something more practical.

Setup project

Let's start by creating a new Rust project from scratch. We well use Cargo for that. Cargo is Rust’s build system and package manager. Here we assume that Rust and Cargo are already installed in the system, please refer to the Rust book if you have problems with that. To create a new project simply run:

$ cargo new learn_gl_with_rust
$ cd learn_gl_with_rust

If you list the files in the directory you’ll see that Cargo has generated two files and one directory for us: a Cargo.toml file and a src directory with a main.rs file inside. We will use main.rs as an entry point where we start writing out application.

Before we start creating graphics we need to create an OpenGL context and an application window to draw in. However, those operations are specific per operating system and OpenGL designed to abstract itself from these operations. This means we have to create a window, define a context, and handle user input all by ourselves.

Luckily, there are quite a few libraries out there that provide this functionality, some of them specifically aimed at OpenGL. Those libraries save us all the operation-system specific work and give us a window and an OpenGL context to render in. One of those libraries is glutin. It allows us to create an OpenGL context, define window parameters, and handle user input, which is plenty enough for our purposes.

In order to use the glutin library, we need to add it as dependencies in our Cargo.toml file:

[dependencies]
glutin = "0.29.1"

Because OpenGL is only a standard/specification and there are many different versions of OpenGL implementation, the location of most of its functions is not known at compile-time and needs to be queried at run-time. It is then the task of the developer to retrieve the location of the functions they need and store them in function pointers for later use.

Thankfully, there are Rust crates for this purpose as well where gl is a popular one, which we are going to use in our project.

To add gl library to dependencies we need to modify Cargo.toml file as follows:

[dependencies]
glutin = "0.29.1"
gl = "0.14.0"

Creating a window

So far we set up a project and figured out which dependencies we need in order to create an application window and OpenGL context. Now it's time to actually create a window.

Initializing an OpenGL window with glutin can be done using the following steps:

Create an EventLoop for handling window and device events.
Specify window specific parameters using glium::glutin::WindowBuilder::new(). We set a window title here.
Specify OpenGL specific attributes using glium::glutin::ContextBuilder::new() and build OpenGL context. We tell glutin that 3.3 is the OpenGL version we want to use.
Make the context of the window current on the calling thread.

let event_loop = EventLoop::new();
let window = WindowBuilder::new().with_title("Learn OpenGL with Rust");

let gl_context = ContextBuilder::new()
    .with_gl(GlRequest::Specific(Api::OpenGl, (3, 3)))
    .build_windowed(window, &event_loop)
    .expect("Cannot create windowed context");

let gl_context = unsafe {
    gl_context
        .make_current()
        .expect("Failed to make context current")
};

Previously we mentioned that gl crate manages function pointers for OpenGL so we want to initialize gl before we call any OpenGL function:

gl::load_with(|ptr| gl_context.get_proc_address(ptr) as *const _);

So far as soon as the window has been created application immediately quit and close the window. We want the application to keep drawing images and handling user input until the program has been explicitly told to stop. For this reason we need to loop forever until we detect that a CloseRequested event has been received. The following code shows how to do it using method run of event_loop:

event_loop.run(move |event, _, control_flow| {
    *control_flow = ControlFlow::Wait;

    match event {
        Event::LoopDestroyed => (),
        Event::WindowEvent { event, .. } => match event {
            WindowEvent::CloseRequested => *control_flow = ControlFlow::Exit,
            _ => (),
        },
        _ => (),
    }
});

The same way we can handle Resized window event that gets called each time the window is resized. We pass new size of the window to gl_context to adjust viewport:

WindowEvent::Resized(physical_size) => gl_context.resize(physical_size),

OpenGL uses what is called double buffering. Instead of drawing directly to the window, we are drawing to an image stored in memory. Once we have finished drawing, this image is copied to the window. In order to do it we call swap_buffers on gl_context once we receive window event RedrawRequested.

To test if things actually work we want to clear the screen with a color of our choice. Otherwise we would still see the results from the previous frame. We can clear the screen's color buffer using gl::Clear where we pass gl::COLOR_BUFFER_BIT.

Event::RedrawRequested(_) => {
    unsafe {
        gl::ClearColor(0.0, 0.0, 1.0, 1.0);
        gl::Clear(gl::COLOR_BUFFER_BIT);
    }
    gl_context.swap_buffers().unwrap();
}

Now if you run cargo run you should see a nice window with a blue background.

Summary

Today we've learned a bit of OpenGL theory as well as how to create a window, initialize OpenGL context and call some basic api to clear a window with a desired color.

Next time we are going to discuss how graphics pipeline of OpenGL works and how we can configure it with shaders. Stay in touch!

If you find the article interesting consider hit the like button and subscribe for updates.

Calling C code from Rust

Yury Samkevich — Wed, 17 Aug 2022 20:03:53 +0000

Rust was originally designed as a systems language for writing high performance applications that are usually written in C or C++. Although Rust solves problems that C/C++ developers have been struggling with for a long time there are countless amount of C and C++ libraries and it makes no sense to replace all of them with Rust. For this reason, Rust makes it easy to communicate with C APIs without overhead, and to leverage its ownership system to provide much stronger safety guarantees for those APIs at the same time.

Rust provides a foreign function interface (FFI) to communicate with other languages. Following Rust's design principles, the FFI provides a zero-cost abstraction where function calls between C and Rust have identical performance to C function calls. FFI bindings can also leverage language features such as ownership and borrowing to provide a safe interface that enforces protocols around pointers and other resources.

In this post we'll explore how to call C code from Rust and to build C and Rust code together as well as how to automate this process. You can find the source code of the complete project on github.

Note: As C++ has no stable ABI for the Rust compiler to target, it is recommended to use C ABI for any interoperability between Rust and C++. Therefore, in this article we will talk about interacting with C code, because the concepts provided here cover both C and C++.

Creating bindings

We will start with a simple example of calling C code from Rust. Let's imagine that we have the following header file:

/* File: libvec/vec.h */
#pragma once

typedef struct Vec2 {
    int x;
    int y;
} Vec2;

void scale(Vec2* vec, int factor);

and corresponding C file:

/* File: libvec/vec.c */
#include "vec.h"

void scale(Vec2* vec, int factor) {
    vec->x *= factor;
    vec->y *= factor;
}

Before we start using any C code from Rust, we need to define all data types and function signatures we are going to interact with in Rust. Usually in C/C++ world we use header files for that purpose, which define all necessary data. But in Rust, we need to either manually translate these definitions to Rust code, or use a tool to generate these definitions.

Let us write a rust file which resembles the C header file:

/* File: src/bindings.rs */
use std::os::raw::c_int;

#[repr(C)]
#[derive(Debug)]
pub struct Vec2 {
    pub x: c_int,
    pub y: c_int,
}

extern "C" {
    pub fn scale(
        vec: *mut Vec2,
        factor: c_int
    );
}

Rust needs to laydown members in a structure the way C would laydown it in memory. For that reason we include the #[repr(C)] attribute, which instructs the Rust compiler to always use the same rules C does for organizing data within a struct.

We declared function scale without defining a body. So, we use extern keyword to indicate the fact that the definition of this function will be provided elsewhere or linked into the final library or binary from a static library.

In the extern block, we have a string, "C", following it. This "C" specifies that we want the compiler to respect the C ABI so that the function-calling convention follows exactly as a function call that's done from C. An Application Binary Interface(ABI) is basically a set of rules and conventions that dictates how types and functions are represented and manipulated at the lower levels. There are also other ABIs that Rust supports such as fastcall, cdecl, win64, and others, but this topic is beyond the scope of the current article.

Generating bindings

So far we manually wrote interface to interact with C. But this approach has some drawbacks. Consider real case scenario where each header file has lots of structure definitions, function declarations, inline functions etc. As well as writing interfaces manually is tedious and error prone. But luckily for us there is a tool called bindgen which can perform these conversions automatically.

We can install bindgen with the following command:

$ cargo install bindgen

The command to generate bindings may look like this:

$ bindgen libvec/vec.h -o src/bindings.rs

Although we can use bindgen as a command line tool because it seems to give you more control over generation, the recommended way to use bindgen is generating the bindings on the fly through build.rs script.

A build.rs script is a file written in Rust syntax, that is executed on your compilation machine, after dependencies of your project have been built, but before your project is built. If you want to know more about build.rs please refer to the documentation. To generate bindings with bindgen we add the build.rs file with the following content:

/* File: build.rs */
extern crate bindgen;
use std::path::PathBuf;

fn main() {
    // Tell cargo to invalidate the built crate whenever the wrapper changes
    println!("cargo:rerun-if-changed=libvec/vec.h");
    let bindings = bindgen::Builder::default()
        // The input header we would like to generate bindings for.
        .header("libvec/vec.h")
        // Tell cargo to invalidate the built crate whenever any of the
        // included header files changed.
        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
        // Finish the builder and generate the bindings.
        .generate()
        .expect("Unable to generate bindings");

    // Write the bindings to the src/bindings.rs file.
    let out_path = PathBuf::from("src");
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Couldn't write bindings!");
}

We also need to add bindgen to build dependencies in Cargo.toml file:

[build-dependencies]
bindgen = "0.53.1"

Now, when we run cargo build, our bindings are generated on the fly to src/bindings.rs file.

Finally, we can use our generated buildings in Rust as in the following example:

/* File: src/main.rs */
use crate::bindings::{scale, Vec2};

mod bindings;

fn main() {
    unsafe{
        let mut vec = Box::new(Vec2{ x: 5, y: 10 });
        scale(&mut *vec, 2);
        println!("scaled vector: {:?}", *vec);
    }
}

Building C code

Since the Rust compiler does not directly know how to compile C code, we need to compile our non-Rust code ahead of time. We can start simple and compile it in static library, which then will be combined with our Rust code at the final linking step.

To compile static library libvec.a from our C code we can use the following command:

$ cc -c libvec/vec.c
$ ar rcs libvec.a vec.o

Now we can link it all together:

$ rustc -l static=vec -L. src/main.rs

This command tells Rust compiler to look for a static libvec.a in the current . path. This should compile and give you the main binary, which can be executed.

Using `cc` crate

It might be quite tedious to compile static library manually every time we make changes in C code. The better solution is to instead utilize the cc crate, which provides an idiomatic Rust interface to the compiler provided by the host.

In our case of compiling a single C file as a dependency to a static library, we can amend out build.rs script using the cc crate. The modified version would look like this:

/* File: build.rs */
extern crate bindgen;
extern crate cc;
use std::path::PathBuf;

fn main() {
    // Tell cargo to invalidate the built crate whenever the wrapper changes
    println!("cargo:rerun-if-changed=libvec/vec.h");
    let bindings = bindgen::Builder::default()
        // The input header we would like to generate bindings for.
        .header("libvec/vec.h")
        // Tell cargo to invalidate the built crate whenever any of the
        // included header files changed.
        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
        // Finish the builder and generate the bindings.
        .generate()
        .expect("Unable to generate bindings");

    // Write the bindings to the src/bindings.rs file.
    let out_path = PathBuf::from("src");
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Couldn't write bindings!");

    // Build static library
    cc::Build::new()
        .file("libvec/vec.c")
        .compile("libvec.a");
}

Updated build dependencies section in Cargo.toml would look like this:

[build-dependencies]
bindgen = "0.53.1"
cc = "1.0"

Now we can simply run cargo build to generate bindings, compile static library and link it with a Rust code. How cool is that!

Using CMake

In real world we usually have existing C projects that often use popular build systems like make or CMake. And it would be very inconvenient to use cc crate to compile them and don't have an option to reuse existing makefiles. Likely for us Rust have cmake crate that is intended to help us.

Let's assume that our vec library uses CMake and we have the following CMakeLists.txt file:

# File: libvec/CMakeLists.txt
cmake_minimum_required(VERSION 3.0)
project(libvec C)

add_library(vec STATIC vec.c)

install(TARGETS vec DESTINATION .)

To use cmake crate we need to add build dependency on it to Cargo.toml file:

[build-dependencies]
bindgen = "0.53.1"
cmake = "0.1.48"

And modify our build.rs file as follows:

/* File: build.rs */
extern crate bindgen;
extern crate cmake;
use cmake::Config;
use std::path::PathBuf;

fn main() {
    // Tell cargo to invalidate the built crate whenever the wrapper changes
    println!("cargo:rerun-if-changed=libvec/vec.h");
    let bindings = bindgen::Builder::default()
        // The input header we would like to generate bindings for.
        .header("libvec/vec.h")
        // Tell cargo to invalidate the built crate whenever any of the
        // included header files changed.
        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
        // Finish the builder and generate the bindings.
        .generate()
        .expect("Unable to generate bindings");

    // Write the bindings to the src/bindings.rs file.
    let out_path = PathBuf::from("src");
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Couldn't write bindings!");

    // Build static library
    let dst = Config::new("libvec").build();
    println!("cargo:rustc-link-search=native={}", dst.display());
    println!("cargo:rustc-link-lib=static=vec");
}

We use cmake::Config type to trigger CMake driven to build our library, telling that it’s code and CMakeFiles.txt files are located in libvec subdirectory and then requesting the build to happen. Next lines write to stdout special command for Cargo to set library search path and pick our libvec.a for linking respectively. After that we can compile our project with cargo build.

Summary

We've talked today about Rust and C interoperability, how to generate bindings to C code and how to automate this process as well as how to use cc and CMake crates to build C code from cargo.

I hope you have found the information above useful and helpful, any questions and feedbacks and welcomed.
If you find this article interesting don't forget to like it and give a start to source code.

DEV Community: Yury Samkevich

Learn OpenGL with Rust: textures

Textures

Render a rectangle

Texture coordinates

Load texture data

Texture units

Summary

Learn OpenGL with Rust: first triangle

Vertex data

Vertex buffer object

Vertex array object

Rendering a triangle

Summary

Learn OpenGL with Rust: shaders

Graphics pipeline

Shaders

Shader program

Summary

Learn OpenGL with Rust: creating a window

Motivation

A bit of OpenGL theory

Setup project

Creating a window

Summary

Calling C code from Rust

Creating bindings

Generating bindings

Building C code

Using cc crate

Using CMake

Summary

Using `cc` crate