Build Mesa OpenGL on VxWorks 5.5 with WindML 3.0

Build Mesa OpenGL on VxWorks 5.5 with WindML 3.0

🎯 1. Introduction

#

OpenGL is a graphics API for rendering two-dimensional and three-dimensional primitives into a framebuffer. It provides a programmable interface for specifying geometric transformations, projection, lighting, textures, and other rendering operations.

Mesa is an implementation of the OpenGL API. It provides a software rendering pipeline and can also support hardware-accelerated rendering when an appropriate graphics driver and integration framework are available.

In the legacy VxWorks development environment described here, Mesa 4.0 can be integrated with WindML 3.0 to provide basic 3D graphics capabilities. This approach allows developers to explore OpenGL programming on VxWorks 5.5 without requiring a dedicated hardware-accelerated graphics stack.

The example uses the following development environment:

• Tornado 2.2
• VxWorks 5.5
• WindML 3.0
• Mesa 4.0
• SIMNTgnu downloadable-project toolchain
• simpc BSP for the simulator-based VxWorks image

Mesa’s rendering implementation in this configuration is software-based. Geometry processing and rasterization are performed by the CPU, and the resulting image is presented through the WindML graphics interface. Consequently, rendering performance is limited compared with a properly integrated hardware-accelerated implementation.

The Direct Rendering Infrastructure (DRI) is associated with graphics-driver integration and direct rendering capabilities on supported platforms. Its driver and operating-system requirements are separate from the legacy WindML configuration covered in this tutorial.

The objective here is to establish a working OpenGL development environment and demonstrate fundamental graphics concepts, including coordinate transformations, projection, lighting, texturing, and display lists. Hardware acceleration and production-grade 3D performance are outside the scope of this implementation.

🧰 2. Prerequisites and Development Environment

#

2.1 Required Software

#

Prepare the following components before building Mesa:

WindML must already be installed and working in the Tornado environment. Mesa does not replace WindML; it uses the WindML UGL (Universal Graphics Library) interface to present rendered graphics.

Before compiling Mesa, verify that a basic WindML application can initialize the graphics environment successfully. This isolates WindML configuration problems from subsequent Mesa compilation or linking problems.

For background on setting up the legacy graphics environment, see the VxWorks WindML 3.0 installation and configuration guide.

2.2 Directory Layout

#

The examples assume that Tornado is installed at:

C:\Tornado2.2

Download Mesa 4.0 and extract the source archive into:

C:\Tornado2.2\target\src

After extraction, the Mesa source tree should contain directories similar to the following:

C:\Tornado2.2\target\src\Mesa\
    include\
    src\
    src-glu\
    windmldemos\

The src directory contains the core OpenGL implementation, software rasterizer, and WindML integration code. The src-glu directory contains the OpenGL Utility Library (GLU). The windmldemos directory contains examples such as uglteapot.c.

The following build procedure uses the source organization of the legacy Mesa 4.0 distribution. Source files and configuration requirements may differ in later Mesa releases.

🏗️ 3. Building the Mesa OpenGL Library

#

The first major task is to compile the required Mesa source files into a static archive that can be linked into a downloadable VxWorks application.

In Tornado 2.2, create a downloadable project using the SIMNTgnu toolchain. Configure the project to build an archive rather than a standalone executable.

The source files are organized into five groups:

• GL: Core OpenGL implementation and software rendering pipeline.
• UGL: WindML graphics backend.
• OS: Off-screen rendering support.
• GLUTSHAPES: Geometric helpers used by the demo.
• GLU: OpenGL utility functions.

Add every required source file listed below to the library project. Omitting a translation unit can result in undefined-symbol errors when the archive or dependent demo is linked.

3.1 GL Core Sources

#

The GL group contains the core OpenGL API implementation, graphics state management, transformation and lighting code, software rasterizer, and vertex-processing pipeline.

Add the following source files from C:\Tornado2.2\target\src\Mesa\src and its corresponding subdirectories.

Core implementation

#

api_arrayelt.c
api_loopback.c
api_noop.c
api_validate.c
accum.c
attrib.c
blend.c
buffers.c
clip.c
colortab.c
config.c
context.c
convolve.c
debug.c
depth.c
dispatch.c
dlist.c
drawpix.c
enable.c
enums.c
eval.c
extensions.c
feedback.c
fog.c
get.c
glapi.c
glthread.c
hash.c
hint.c
histogram.c
image.c
imports.c
light.c
lines.c
matrix.c
mem.c
mmath.c
pixel.c
points.c
polygon.c
rastpos.c
state.c
stencil.c
texformat.c
teximage.c
texobj.c
texstate.c
texstore.c
texutil.c
varray.c
vtxfmt.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src

X86 helper sources

#

X86/x86.c
X86/common_x86.c
X86/3dnow.c
X86/sse.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src\X86

These files provide architecture-specific helper implementations. Confirm that the selected source variants are appropriate for the intended target and compiler configuration.

Mathematics and transformation sources

#

math/m_debug_clip.c
math/m_debug_norm.c
math/m_debug_vertex.c
math/m_debug_xform.c
math/m_eval.c
math/m_matrix.c
math/m_translate.c
math/m_vector.c
math/m_vertices.c
math/m_xform.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src\math

Array-cache sources

#

array_cache/ac_context.c
array_cache/ac_import.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src\array_cache

Software rasterizer sources

#

swrast/s_aaline.c
swrast/s_aatriangle.c
swrast/s_accum.c
swrast/s_alpha.c
swrast/s_alphabuf.c
swrast/s_bitmap.c
swrast/s_blend.c
swrast/s_buffers.c
swrast/s_copypix.c
swrast/s_context.c
swrast/s_depth.c
swrast/s_drawpix.c
swrast/s_feedback.c
swrast/s_fog.c
swrast/s_histogram.c
swrast/s_imaging.c
swrast/s_lines.c
swrast/s_logic.c
swrast/s_masking.c
swrast/s_pb.c
swrast/s_pixeltex.c
swrast/s_points.c
swrast/s_readpix.c
swrast/s_scissor.c
swrast/s_span.c
swrast/s_stencil.c
swrast/s_texture.c
swrast/s_texstore.c
swrast/s_triangle.c
swrast/s_zoom.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src\swrast

The software rasterizer implements low-level rendering operations, including pixel processing, span generation, line drawing, and triangle rasterization. In this configuration, these functions perform the rendering work without a hardware-accelerated graphics pipeline.

Software rasterizer setup sources

#

swrast_setup/ss_context.c
swrast_setup/ss_triangle.c
swrast_setup/ss_vb.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src\swrast_setup

Transform and lighting pipeline sources

#

tnl/t_array_api.c
tnl/t_array_import.c
tnl/t_context.c
tnl/t_eval_api.c
tnl/t_imm_alloc.c
tnl/t_imm_api.c
tnl/t_imm_debug.c
tnl/t_imm_dlist.c
tnl/t_imm_elt.c
tnl/t_imm_eval.c
tnl/t_imm_exec.c
tnl/t_imm_fixup.c
tnl/t_pipeline.c
tnl/t_vb_fog.c
tnl/t_vb_light.c
tnl/t_vb_normals.c
tnl/t_vb_points.c
tnl/t_vb_render.c
tnl/t_vb_texgen.c
tnl/t_vb_texmat.c
tnl/t_vb_vertex.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src\tnl

The transform-and-lighting pipeline processes vertex data, applies transformations and lighting, and prepares primitives for rasterization.

Together, these GL sources provide the primary OpenGL execution path used by the WindML demo.

3.2 UGL and WindML Backend Sources

#

The UGL group provides the integration layer between Mesa and WindML.

Add the following files:

windml/ugl_api.c
windml/ugl_dd.c
windml/ugl_span.c
windml/ugl_line.c
windml/ugl_tri.c
windml/tornado/torMesaUGLInit.c

The files are located under:

C:\Tornado2.2\target\src\Mesa\src

The first five files belong to the windml directory, while torMesaUGLInit.c belongs to windml\tornado.

The backend translates Mesa rendering operations into output operations supported by the UGL interface. Rasterized spans, lines, and triangles are passed through this layer to the configured WindML graphics device.

The torMesaUGLInit.c file provides Tornado-specific initialization for this integration.

Correct configuration of this backend depends on the availability of the WindML development headers and compatible libraries.

3.3 OSMesa and Operating-System Integration Sources

#

The OS group includes Mesa’s off-screen software rendering interface and the Tornado-specific initialization source.

Add:

OSmesa/osmesa.c
windml/tornado/torMesaOSInit.c

The source files are located at:

• C:\Tornado2.2\target\src\Mesa\src\OSmesa\osmesa.c
• C:\Tornado2.2\target\src\Mesa\src\windml\tornado\torMesaOSInit.c

OSMesa provides an off-screen software rendering interface. It is included in this build alongside the WindML rendering backend.

Off-screen rendering and display output are separate capabilities. Including OSMesa does not eliminate the need to configure the WindML graphics components required by uglteapot.

3.4 GLUTSHAPES Sources

#

The GLUTSHAPES group provides geometric helpers for rendering predefined objects, including the teapot used by the example application.

Add:

windml/ugl_glutshapes.c
windml/tornado/torGLUTShapesInit.c

Source directory:

C:\Tornado2.2\target\src\Mesa\src

These files provide UGL-based geometric helper functions for the WindML implementation. They replace the assumption of a conventional X11-based display environment with the interfaces available in the target graphics stack.

The uglteapot demo uses this functionality to generate the teapot geometry.

3.5 GLU Utility Library Sources

#

The OpenGL Utility Library provides higher-level operations built on top of the core OpenGL API, including quadrics, tessellation, projection helpers, mipmap generation, and NURBS support.

Add the following files from:

C:\Tornado2.2\target\src\Mesa\src-glu

glu.c
mipmap.c
nurbs.c
nurbscrv.c
nurbssrf.c
nurbsutl.c
polytest.c
project.c
quadric.c
tess.c
tesselat.c

Also add the Tornado initialization source:

C:\Tornado2.2\target\src\Mesa\src\windml\tornado\torMesaGLUInit.c

This file appears as a relative path in the legacy source organization:

../src/windml/tornado/torMesaGLUInit.c

When adding the file through Tornado’s project interface, use its actual filesystem path.

3.6 Validate the Source Inventory

#

Before configuring the archive build, verify that every source file listed above has been added to the correct project.

In particular, check the following groups:

• GL core and supporting mathematics.
• Architecture-specific helpers required by the configuration.
• Software rasterizer and transformation pipeline.
• UGL/WindML backend.
• OSMesa integration.
• GLUTSHAPES helpers.
• GLU utility functions.

The names and directory structure in this guide reflect the legacy Mesa 4.0 source tree. If a file is absent from the package, verify the archive version and its directory layout instead of silently substituting a source file from another release.

📁 4. Preparing the OpenGL Headers

#

The application project needs access to the public OpenGL and Mesa-specific headers.

Create the following directory if it does not already exist:

C:\Tornado2.2\target\h\GL

Copy these six header files from:

C:\Tornado2.2\target\src\Mesa\include

into the new GL directory:

gl.h
glext.h
glu.h
osmesa.h
uglglutshapes.h
uglmesa.h

The resulting directory should contain:

C:\Tornado2.2\target\h\GL\
    gl.h
    glext.h
    glu.h
    osmesa.h
    uglglutshapes.h
    uglmesa.h

This allows applications to reference the public OpenGL headers using include statements such as:

#include <GL/gl.h>

The header installation and the compiler’s include paths serve related but different purposes. The public headers make the interfaces available to application code, while the Mesa source include directories are also needed when compiling the library itself.

🔧 5. Configuring and Building the Mesa Archive

#

After adding the source files and preparing the headers, configure the Tornado project to build a static archive.

5.1 Configure the Compiler Include Paths

#

Open the Mesa library project in Tornado and select the Builds tab.

Edit the C/C++ Compiler options and add the following include directories:

C:\Tornado2.2\target\src\Mesa\include
C:\Tornado2.2\target\src\Mesa\src

The first directory contains the Mesa public headers used by the library’s source files. The second directory contains internal headers used by the core renderer, software rasterizer, mathematics routines, and WindML integration.

These directories are needed in addition to the public header location under target\h.

If the compiler reports missing headers, verify the exact include search paths and confirm that the paths match the extracted source tree.

5.2 Select the Archive Build Rule

#

Open the project’s Rules tab and change the build rule to archive.

Mesa is being built as a reusable library. The intended output is a static archive rather than an independently downloadable application.

The archive will be linked later into the uglteapot downloadable project.

5.3 Build and Verify the Library

#

Build the project and inspect the output for compilation or linking errors.

The example assumes that Tornado generates the following archive:

C:\Tornado2.2\target\proj\MesaLib\SIMNTgnu\MesaLib.a

The same path can be written with forward slashes in Tornado build settings:

C:/Tornado2.2/target/proj/MesaLib/SIMNTgnu/MesaLib.a

If the project uses a different name or directory, use the actual archive path produced by the build.

Before moving on, verify that:

• The archive exists.
• The build completed successfully.
• Required source files were compiled.
• No unresolved internal dependencies remain.
• The generated artifact corresponds to the expected SIMNTgnu configuration.

A successful archive build does not prove that every function needed by the demo is available. Unresolved references may only become visible when the downloadable application is linked.

🖥️ 6. Building the VxWorks Image with WindML

#

The Mesa library project does not produce a bootable operating-system image. A separate VxWorks project must provide the WindML environment in which the demo executes.

6.1 Create a VxWorks Image Project

#

Create a VxWorks image project based on the simpc BSP.

Include the following WindML components:

• complete 2D graphics library
• simulator host devices
• Simulator graphics

These components provide the minimum graphics and host-device support required by the example configuration.

The selected BSP is important. The simulator graphics driver must be compatible with the image configuration and with the WindML interface expected by Mesa.

6.2 Understand the Toolchain and BSP Distinction

#

The two project types serve different purposes in this workflow.

SIMNTgnu is used for the downloadable Mesa library project and the uglteapot application project.

simpc is used to build the VxWorks image that runs the application and supplies the configured WindML environment.

These settings are related but are not interchangeable. Use the toolchain required by the downloadable project’s build configuration, and use the BSP selected for the operating-system image.

6.3 Build and Boot the Image

#

Build the VxWorks image with the required WindML components enabled.

Boot the image in the simulator and verify that the operating system starts normally.

Before debugging Mesa, confirm that the WindML display initializes successfully and that the simulator provides a usable graphics output path. This separates problems in the base graphics environment from failures in the OpenGL library or demo.

The steps for configuring the simulator image are not repeated in detail here. For the corresponding legacy WindML configuration workflow, refer to the VxWorks WindML 3.0 setup guide.

🚀 7. Building and Running the uglteapot Demo

#

The uglteapot sample demonstrates that the Mesa library can initialize the WindML backend and render a three-dimensional object.

The procedure uses a separate downloadable project, which links the Mesa archive built in Section 5.

7.1 Create the Downloadable Project

#

Create a new downloadable project based on the SIMNTgnu toolchain.

Use the same toolchain as the Mesa archive project to maintain compatibility between the compiled objects and the downloadable application.

Add the following source file:

C:\Tornado2.2\target\src\Mesa\windmldemos\uglteapot.c

The source file contains the launcher function and the sample’s rendering entry point.

7.2 Configure the taskSpawn Call

#

In uglteapot.c, locate the taskSpawn call and change the first demo argument from UGL_FALSE to UGL_TRUE.

The launcher should follow this pattern:

void uglteapot(void)
{
    taskSpawn(
        "tTeapot",
        210,
        VX_FP_TASK,
        100000,
        (FUNCPTR)windMLTeapot,
        UGL_TRUE,
        1, 2, 3, 4, 5, 6, 7, 8, 9
    );
}

The significant arguments are:

• "tTeapot": Name assigned to the spawned task.
• 210: Task priority.
• VX_FP_TASK: Enables the floating-point task context required by the example’s floating-point operations.
• 100000: Requested task stack size in bytes.
• windMLTeapot: Entry point for the demo’s rendering task.
• UGL_TRUE: Boolean argument expected by this example configuration.

The remaining integer values satisfy the example’s taskSpawn argument list. Preserve the original function signature and expected arguments when adapting the sample.

Confirm that the demo source declares or references windMLTeapot correctly and that the corresponding implementation is included in the project or available through the linked library.

7.3 Link the Mesa Archive

#

Open the downloadable project and select the Builds tab.

Edit the Macros settings and add the path to the Mesa archive under PRJ_LIBS.

For example:

PRJ_LIBS = C:/Tornado2.2/target/proj/MesaLib/SIMNTgnu/MesaLib.a

If the project already contains other required libraries in PRJ_LIBS, retain them and append the Mesa archive using the syntax supported by the installed Tornado project configuration.

Adding a compiler include path is not sufficient to link Mesa. The archive must be supplied to the linker so that the symbols referenced by the demo can be resolved.

7.4 Build the Downloadable Application

#

Build the uglteapot project.

The expected result is a downloadable .out file in the project’s output directory.

If linking fails, investigate the errors in the following order:

1. Confirm that the Mesa archive exists and points to the intended build output.
2. Verify that all required Mesa source files were added to the archive project.
3. Check that the demo uses the same compatible toolchain as the library.
4. Verify that the required WindML and GLU initialization functions are present.
5. Confirm that PRJ_LIBS includes the correct archive path.

Undefined symbols frequently indicate missing object files, unresolved library dependencies, or an incorrect link configuration.

7.5 Download and Execute the Demo

#

Boot the VxWorks image built in Section 6.

Open the Tornado shell and connect to the running target. Download the .out file produced by the uglteapot project.

After the download completes, invoke the launcher from the shell:

uglteapot

The command is the exported C function name, not the .out filename.

The launcher spawns the tTeapot task, which invokes windMLTeapot and initializes the demo’s rendering path.

7.6 Expected Results and Keyboard Controls

#

When the demo initializes successfully, the simulator should display the three-dimensional teapot.

The sample supports the following controls:

These controls depend on the keyboard and input interfaces available in the selected WindML configuration.

If the teapot does not appear, confirm that the VxWorks image is running, the target accepts downloads, and the application uses the correct Mesa archive.

🔍 8. Performance Characteristics and Limitations

#

The legacy Mesa 4.0 and WindML 3.0 combination is useful for learning OpenGL, but its software-rendering implementation has important limitations.

8.1 Software Rendering Performance

#

The described graphics path uses Mesa’s CPU-based software rasterizer. Geometry processing and rendering are performed by software, and the resulting image is transferred through the UGL/WindML interface.

The simpc environment can display the demo correctly, but rendering is comparatively slow because the graphics work is performed in software.

Performance depends on the complexity of the scene, framebuffer configuration, CPU resources, and the cost of transferring rendered output.

This setup is best suited to basic development and functional validation rather than performance-sensitive 3D applications.

8.2 Double Buffering and Display Artifacts

#

The original WindML rendering path described here does not support the double-buffered presentation expected by this demo configuration.

As a result, the image may flicker or show intermediate rendering states while the teapot is drawn. These artifacts do not necessarily indicate a compilation or initialization failure.

The visible behavior depends on the configured graphics backend and its supported buffer-management features. Diagnose display artifacts separately from failures to initialize the OpenGL context or access the framebuffer.

8.3 Hardware Acceleration

#

This configuration does not provide the hardware-accelerated rendering path required by demanding 3D applications.

Using a different Mesa version or enabling additional software features does not automatically enable GPU acceleration. Hardware acceleration requires a compatible driver, supported graphics hardware, and integration with the operating system and graphics stack.

The legacy WindML and Mesa configuration in this tutorial is intended to demonstrate fundamental OpenGL concepts. Applications requiring substantially higher rendering performance need a supported accelerated graphics implementation.

📋 9. Configuration Quick Reference

#

✅ 10. Conclusion

#

Building Mesa OpenGL on VxWorks 5.5 with WindML 3.0 provides a practical introduction to embedded 3D graphics development in a legacy Tornado environment.

The process involves compiling the required Mesa 4.0 source files into a static archive, preparing the public OpenGL headers, building a VxWorks image with the necessary WindML components, and linking the archive into a downloadable application.

The uglteapot demo validates the integration by initializing the OpenGL rendering path and displaying a three-dimensional teapot through WindML.

Although this configuration does not provide hardware acceleration and may exhibit slow rendering or display artifacts, it offers a foundation for learning transformations, projection, lighting, and other fundamental OpenGL techniques.

The key to a reliable build is keeping the Mesa library project, downloadable application, VxWorks image, and WindML configuration consistent. Once that environment is working, developers can use the sample as a foundation for experimenting with OpenGL APIs and implementing simple 3D graphics applications on legacy VxWorks systems.