UM2547 User manual STM32MP157 GPU tool kit Introduction The STMicroelectronics STM32MP157 line microprocessors embed a Vivante GPU (graphics processor unit) that uses the Khronos® Group OpenGL® ES (embedded system) and OpenVG™ standards. This document describes the STM32MP157 GPU tool kit (STM32MP157GPUTK), a set of applications allowing developers to rapidly develop and port graphic applications. Thanks to STM32MP157GPUTK, any graphics-based application can be accelerated, improving the eye-catching visuals and minimizing the system resources loading (CPU, memory, bandwidth, power). Good understanding of OpenGL®/OpenGL® ES programming fundamentals, is recommended before reading this user manual. See the related STM32MP157 documentation [1], [2] for more technical details. This document contains proprietary copyright material disclosed with permission of Vivante Corporation. Reference documents [1] STM32MP157 advanced Arm®-based 32-bit MPUs reference manual (RM0436) [2] STM32MP157 GPU application programming manual (PM0263) UM2547 - Rev 1 - March 2019 www.st.com For further information contact your local STMicroelectronics sales office. UM2547 STM32MP157GPUTK overview 1 STM32MP157GPUTK overview This tool kit applies to the STM32MP157 Arm®-based microprocessors (MPUs). Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 1.1 STM32MP157GPUTK components overview STM32MP157GPUTK includes the following components (also named vTools): • vProfiler: driver and hardware performance profiling utility • vAnalyzer: visual analyzer for graphing the performance metrics The following pre-processing utilities are also provided: • vShader for standalone development of optimized shader programs • vCompiler for compiling shader code into binary executables • vTexture for image transfer providing compression and decompression options Figure 1. STM32MP157GPUTK vTools components STM32MP157 MPU STM32MP157GPUTK STM32MP157GPUTK Graphics on-target utility Windows or Linux on-host utilities applications vShader vTexture Prototype and Compress and Application optimize shader decompress images framework programs OpenGL ES vProfiler vAnalyzer vCompiler Collect real-time Visual analysis of Shader programs OpenVG performance metrics performance metrics compile and link 1.2 STM32MP157GPUTK operating system requirements Most vTools applications are designed to run on Windows® 32- and 64-bit operating systems (OS). Some components, such as vProfiler and vCompiler, are run on other platforms. Refer to the individual vTools detailed description in the next sections. UM2547 - Rev 1 page 2/39 UM2547 STM32MP157GPUTK installation 1.3 STM32MP157GPUTK installation STM32MP157GPUTK contains a vtools folder, including four .zip packages that can be individually extracted. As an example, if the system has 7-Zip installed, right click and select Extract Here. A folder is then created with the same name as the .zip file, as listed below: • vAnalyzer.zip • vCompiler.zip • vShader.zip • vTexture.zip Note: vProfiler is not included in the .zip package because it is integrated in the GPU graphics drivers build process and runs on the hardware target. Each vTools extracted folder contains a setup.exe and a vToolName.msi files. The tool can be installed independently by running the setup.exe located in that folder. Typical licensing and folder placement options may appear as part of the installation prompts. vAnalyzer and vShader have a Windows GUI (graphical user interface). vCompiler and vTexture are utilities run from the command line. The STM32MP157GPUTK default installation location is usually a folder named for example C:\Program Files\Vivante\vToolName, where vToolName is the name of the tool being installed. Some systems may install to a Program Files (x86) folder. Note: Windows navigation instructions such as Control Panel navigation vary with the different Windows OS. Administrator rights may be required to install the tool. To install an updated version, use Windows Add/Remove programs to remove the installed version of the tool before installing the new one. UM2547 - Rev 1 page 3/39 UM2547 vShader 2 vShader vShader is a complete off‐line environment for editing, previewing, analyzing, and optimizing shader programs. Thanks to vShader, users can perform all the following tasks: • Map any texture onto shaders • Import user‐defined meshes • Bind mesh attributes to shaders • Set uniforms in shaders • View shader compiler output for optimization hints • Predict hardware performance 2.1 vShader components By default, the vShader executable installs in the following location within STM32MP157GPUTK directories: C:\Program Files\Vivante\vShader vShader includes samples of shader programs, a number of standard meshes (such as sphere, cube, tea pot and pyramid) and a text editor. By combining vertex shaders and fragment shaders into a single shader program, an application can produce a shader effect. A project can use many shader effects, that can share vertex and fragment shaders, mixing and matching to achieve the desired results. Next sections cover the vShader user interface. Tutorials provided with the vShader package are there to help the reader learn about shaders. 2.2 Getting started with vShader Once vShader is launched (clicking on a shortcut or directly on the vShader.exe executable), projects can be created, developed and saved. Project files have a .vsp extension. 2.2.1 Creating a new project To create a new project, locate the main menu bar Select File then New Project… Depending on the current project status, one of three things happens: • If vShader is launched for the first time, there is no project already open and selecting File > New Project… has no effect. • If there have been no changes to the current project since the last save, the current project closes and a new empty project is opened. • If the current project has been modified, a dialog box pops up to ask if changes must be saved. Choosing Yes commits the changes to the current project and close it. A new empty project is opened. 2.2.2 Opening an existing project The following steps are needed to open an existing project: 1. Locate the main menu bar. 2. Select File then Open Project… 3. Double-click on the desired project from the list that pops up or single-click on the project name and click OK. The project is loaded into vShader and appears in the last saved state. UM2547 - Rev 1 page 4/39 UM2547 vShader navigation 2.2.3 Saving a project The following steps are needed to save a project: 1. Locate the main menu bar. 2. Select File then Save Project… 3. Indicate where to save the project in the resulting dialog box, then click OK. 2.3 vShader navigation vShader runs on Windows platforms and is driven from a GUI shown in the figure below. Figure 2. vShader GUI main window The main GUI components are listed below: • menu bar and icons (on the upper part of the window) • Preview and Project Explorer panes (on the left) • Shader Editor pane (on the right) • InfoLog pane (on the lower part) UM2547 - Rev 1 page 5/39 UM2547 vShader navigation 2.3.1 vShader menu bar The main window opens when a user launches vShader. The main menu bar contains drop‐down menus for File, Edit, View, Mesh, Build, and Help, detailed in the table below. Table 1. vShader menu commands Menu Command Description Creates a new project file. If a project is currently open, the user is New Project… prompted to choose whether to save it first. Open Project… Browses for and loads a .vsp vShader project. Saves the current project. If this is the first time saving this project, the Save Project… user is prompted to choose where to save it. File Load Vertex… Browses for and loads a vertex shader fromanexisting text file. Load Fragment… Browse for and load a fragment shader fromanexisting text file. Save VertexShader As… Prompts for filename and location to save the active vertex shader Save FragmentShader As… Prompts for filename and location to save the active fragment shader Exit Closes all open files and exit vShader. Undo [Ctrl-z] Reverts to a previous edit state (only 1-level deep). Redo [Ctrl-z] Re-applies the last “undone” edit command (only 1-level deep). Cut [Ctrl-x] Deletes the selected items and saves a copy in the paste buffer. Edit Copy [Ctrl-c] Saves a copy of the selected items in the paste buffer. Paste [Ctrl-v] Inserts the contents of the paste buffer. Delete [Del or Bkspc] Removes the selected items. Select All [Ctrl-a] Highlights all items in the current view. Reset Preview Resets Preview window. Saves current preview image to a bitmap bmp file. A dialog is displayed Snapshot to let the user choose where to save the bmp. Perspective Uses perspective projection in the Shader Preview pane. Ortho Uses orthographic projection in the Shader Preview pane. View Tool Bar Shows or hides toolbar icons. Preview Window Shows or hides Preview window. Project Explorer Shows or hides Project Explorer window. Shader Editor Shows or hides Shader Editor window. InfoLog Shows or hides InfoLog window. UM2547 - Rev 1 page 6/39 UM2547 vShader navigation Menu Command Description Conic Spiral horn Cube 3D cube Klein Klein bottle Plane 2D square Mesh Sphere Ball Teapot Utah teapot Torus Donut Trefoil Trefoil knot Custom Mesh… Browses for and opens a 3DS mesh file. Compiles the active shader. This command is also available via the Compile Compile button in the Shader Editor window pane. Build Links the vertex and fragment shaders into a shader program and Link applies it to the mesh showed in the Shader Preview window pane. Clear InfoLog Removes all text currently showed in the InfoLog window pane. Help About Information about the used vShader version UM2547 - Rev 1 page 7/39 UM2547 vShader navigation 2.3.2 vShader window panes There are four window panes in the vShader GUI: Preview, Project Explorer, Shader Editor and InfoLog. Each pane can be resized by left‐mouse‐dragging the pane edge. A pane can be hidden by clicking the X in the upper‐right corner of the pane, or by un‐checking the box next to its name in the View pull‐down of the main menu.