Início rápido

Arquivos-fonte

Esta página foi gerada com base nos seguintes arquivos-fonte:

• README.md
• demo/README
• demo/demo.sln
• demo/premake4.lua
• src/Makefile
• demo/ui/Makefile
• demo/noui/Makefile
• src/embed.c
• src/test_gl.cpp
• src/test_ui.cpp

O microprofile é um profiler embutível para CPU/GPU que oferece visualizadores tanto in-app quanto em HTML. Trata-se de um fork do projeto original de Jonas Meyer, com divergências significativas em relação à versão upstream, incluindo suporte aprimorado para UI na tela, suporte a iOS/Android, e melhorias de desempenho no servidor web (README.md:1-52).

Visão geral do projeto

O microprofile permite criar regiões hierárquicas para medir seções de código, adicionar rótulos (labels) com informações extras em forma de strings, e suporta regiões GPU com sincronização de timestamp para D3D11, D3D12, OpenGL e Vulkan. A biblioteca oferece visualização através de UI in-game, navegador web (servidor embutido) ou arquivo HTML, com overhead reduzido (README.md:1-19).

A biblioteca é conhecida por funcionar em Windows XP e superior, Linux, OSX, iOS, Android e Xbox One. A adaptação para outras plataformas é considerada relativamente simples, com pull requests bem-vindos pela comunidade (README.md:20-25).

Requisitos de ambiente

Dependências obrigatórias

Para compilar os exemplos de demonstração, é necessário ter o SDL2 instalado. O projeto assume que o SDL2 está disponível no sistema ou compilado localmente (demo/README:1-6).

Windows: O SDL2 deve estar presente e compilado na subpasta demo/sdl2. A ferramenta premake4 é necessária para gerar a solução do Visual Studio 2012 (demo/README:1-6).

OSX: O SDL2 deve estar compilado e instalado no sistema, de forma que o comando sdl2-config esteja disponível no PATH (demo/README:1-6).

Dependências por plataforma

Ferramentas de build

O projeto suporta múltiplos sistemas de build:

• Premake4: Para geração de projetos Visual Studio no Windows
• Makefiles: Para compilação em Linux e OSX
• Visual Studio: Solução pronta disponível em demo/demo.sln

Instalação e compilação

Caminho recomendado: Makefile em Linux/OSX

Para compilar rapidamente o demo com UI em sistemas Unix-like:

bash
1cd demo/ui
2make embed

Este comando compila primeiro a ferramenta embed (necessária para gerar o HTML embutido) e depois compila o demo completo (demo/ui/Makefile:53-56).

Compilação no Windows com Visual Studio

O projeto inclui uma solução do Visual Studio pronta em demo/demo.sln, configurada para Visual Studio 2015 com suporte às configurações Debug e Release, tanto para x86 quanto x64 (demo/demo.sln:1-28).

A solução contém o projeto noui_d3d11 que demonstra o uso do profiler com Direct3D 11, sem interface gráfica na tela (demo/demo.sln:6-7).

Compilação com Premake4

Para gerar projetos personalizados usando Premake4:

bash
1cd demo
2premake4 vs2012

O script Premake4 configura três projetos distintos (demo/premake4.lua:1-72):

O projeto ui define as macros MICROPROFILE_UI=1 e MICROPROFILE_WEBSERVER=1, habilitando tanto a interface na tela quanto o servidor web embutido (demo/premake4.lua:14).

Estrutura de build detalhada

Configuração do projeto UI

O Makefile do demo UI em demo/ui/Makefile detecta automaticamente o sistema operacional e configura as flags de linkagem apropriadas (demo/ui/Makefile:1-7):

makefile
1ifeq ($(UNAME_S),Linux)
2    LDFLAGS=-lGL `sdl2-config --static-libs` -lpthread
3endif
4ifeq ($(UNAME_S),Darwin)
5    LDFLAGS=-framework OpenGL `sdl2-config --static-libs` -lpthread
6endif

As flags de compilação incluem warnings estritos (-Wall -Werror) e definem as macros necessárias para habilitar a UI e o servidor web (demo/ui/Makefile:9-12):

makefile
1CFLAGS=`sdl2-config --cflags` -I../.. -I../glew -DGLEW_STATIC
2CFLAGS+=-Wall -DMICROPROFILE_UI=1 
3CFLAGS+=-DMICROPROFILE_WEBSERVER=1

Configuração do projeto noui

O demo sem UI em demo/noui/Makefile oferece uma alternativa mais leve, sem dependências de OpenGL ou SDL2 para renderização (demo/noui/Makefile:1-17):

makefile
1CFLAGS=-Wno-c++11-extensions -I../..
2CFLAGS+=-Wall -DMICROPROFILE_UI=0 -DMICROPROFILE_WEBSERVER=1 -DMICROPROFILE_GPU_TIMERS=0

Esta configuração desabilita explicitamente a UI (MICROPROFILE_UI=0) e os GPU timers (MICROPROFILE_GPU_TIMERS=0), mantendo apenas o servidor web habilitado (demo/noui/Makefile:11).

Geração do HTML embutido

A ferramenta embed em src/embed.c é responsável por converter o arquivo HTML do profiler em um header C++ embutido. O Makefile principal em src/Makefile orquestra este processo (src/Makefile:12-24):

makefile
1../microprofilehtml.h: embed.o microprofile.html
2    ./embed.o $@ microprofile.html ____embed____ g_MicroProfileHtml MICROPROFILE_EMBED_HTML

A ferramenta embed aceita cinco argumentos: arquivo de destino, arquivo fonte HTML, padrão de busca, símbolo e define de compilação (src/embed.c:86-90).

Exemplos de uso da API

Inicialização básica do profiler

O arquivo src/test_ui.cpp demonstra o uso mínimo da API do microprofile. A inicialização requer a definição das macros de implementação antes de incluir os headers (src/test_ui.cpp:1-5):

cpp
1#define MICROPROFILE_IMPL
2#define MICROPROFILEUI_IMPL
3
4#include "microprofile.h"
5#include "microprofileui.h"

O fluxo básico de uso envolve criar o profiler na thread principal, usar as macros de escopo para medir regiões de código, e finalizar corretamente ao sair (src/test_ui.cpp:19-36):

cpp
1int main()
2{
3    MicroProfileSetForceEnable(true);
4    MicroProfileOnThreadCreate("Main");
5
6    {
7        MICROPROFILE_SCOPEI("Group", "Name", -1);
8        MICROPROFILE_LABEL("Group", "Label");
9        MICROPROFILE_LABELF("Group", "Label %d", 5);
10    }
11
12    MicroProfileFlip();
13    MicroProfileDraw(128, 64);
14    MicroProfileOnThreadExit();
15}

Profiling com GPU timers OpenGL

O arquivo src/test_gl.cpp demonstra a integração com GPU timers via OpenGL. A macro MICROPROFILE_GPU_TIMERS_GL deve ser definida como 1 antes de incluir os headers (src/test_gl.cpp:14-22):

cpp
1#define MICROPROFILE_IMPL
2#define MICROPROFILEUI_IMPL
3#define MICROPROFILEDRAW_IMPL
4#define MICROPROFILE_GPU_TIMERS_GL 1
5
6#include "microprofile.h"
7#include "microprofileui.h"
8#include "microprofiledraw.h"

O exemplo mostra o uso combinado de scopes CPU e GPU, permitindo correlacionar o trabalho submetido à GPU com o tempo gasto na CPU (src/test_gl.cpp:30-36):

cpp
1{
2    MICROPROFILE_SCOPEI("Group", "Name", -1);
3    MICROPROFILE_SCOPEGPUI("NameGpu", -1);
4    MICROPROFILE_LABEL("Group", "Label");
5    MICROPROFILE_LABELF("Group", "Label %d", 5);
6}

Macros principais da API

Verificação e validação

Compilação dos testes unitários

O Makefile em src/Makefile inclui um target de teste que compila e executa automaticamente os arquivos de teste (src/Makefile:14-18):

bash
1cd src
2make test

Este comando compila todos os arquivos test_*.cpp e os executa automaticamente. Os testes são marcados como intermediários e são removidos após a execução (src/Makefile:26).

Verificação da compilação do demo

Após compilar o demo UI, o executável demo (ou demo.exe no Windows) deve ser gerado no diretório correspondente. A execução do demo deve abrir uma janela SDL2 com a visualização do profiler (demo/ui/Makefile:24).

Para o demo sem UI, o executável demo_noui deve iniciar sem abrir janela, mas com o servidor web ativo (porta padrão não especificada nos arquivos fonte - requer confirmação via documentação adicional ou código fonte principal).

Problemas comuns e soluções

SDL2 não encontrado

Sintoma: Erro de compilação indicando que SDL2/SDL.h não pode ser encontrado.

Solução: Verificar se o SDL2 está instalado corretamente. Em Linux, instalar via gerenciador de pacotes:

bash
1# Ubuntu/Debian
2sudo apt-get install libsdl2-dev
3
4# Fedora
5sudo dnf install SDL2-devel
6
7# OSX (com Homebrew)
8brew install sdl2

Confirmar se sdl2-config está disponível no PATH executando sdl2-config --version (demo/README:1-6).

Erro de linkagem com OpenGL

Sintoma: Erros de símbolo não definido relacionados a funções OpenGL durante a linkagem.

Solução: Verificar se as bibliotecas OpenGL estão instaladas e se as flags de linkagem corretas estão sendo usadas. O Makefile detecta automaticamente o sistema operacional e ajusta as flags (demo/ui/Makefile:1-7).

Em Linux, pode ser necessário instalar os pacotes de desenvolvimento OpenGL:

bash
1sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev

Header microprofile_html.h não encontrado

Sintoma: Erro de compilação indicando que microprofile_html.h não existe.

Solução: Este arquivo é gerado automaticamente pela ferramenta embed. Executar o target embed antes de compilar o demo (demo/ui/Makefile:53-56):

bash
1cd demo/ui
2make embed

Alternativamente, compilar primeiro o src:

bash
1cd src
2make

Warnings tratados como erros

Sintoma: Compilação falha com warnings sendo tratados como erros (-Werror).

Solução: Os Makefiles usam flags estritas de compilação. Para desenvolvimento, pode-se temporariamente remover -Werror das flags (demo/ui/Makefile:9):

makefile
1# Linha original
2CFLAGS+=-Wall -Werror
3
4# Modificação temporária
5CFLAGS+=-Wall

Problemas com Premake4 no Windows

Sintoma: O comando premake4 não é reconhecido ou gera erros.

Solução: Verificar se o Premake4 está instalado e no PATH. O projeto requer especificamente a versão 4.x do Premake. Baixar de https://premake.github.io/download.html e adicionar ao PATH do sistema (demo/premake4.lua:1-3).

Como alternativa, usar a solução Visual Studio existente em demo/demo.sln (demo/demo.sln:1-28).

Próximos passos

Após compilar e executar os demos com sucesso, recomenda-se explorar:

1. Integração em projeto existente: Copiar os arquivos microprofile.h, microprofileui.h e microprofile_html.h para o projeto e seguir o padrão de inicialização demonstrado em src/test_ui.cpp

2. Configuração de GPU timers: Para projetos que usam OpenGL, Direct3D 11/12, ou Vulkan, consultar src/test_gl.cpp para exemplos de integração com GPU profiling

3. Modos de visualização: Experimentar tanto a UI in-game quanto o servidor web embutido para determinar qual se adequa melhor ao fluxo de trabalho

4. Customização: Revisar as macros de configuração disponíveis nos headers para ajustar o comportamento do profiler às necessidades específicas do projeto