GL_INTEL_performance_queries (unofficial unstable incomplete documentation)

Introduction

There are a number of OpenGL extensions related to GPU timing and performance: GL_ARB_timer_query (supported by modern NVIDIA and ATI/AMD drivers on Windows and Linux for most of their devices), GL_EXT_timer_query (supported on those plus older drivers, and some Mesa drivers on Linux), GL_AMD_performance_monitor (supported by ATI/AMD drivers).

There's also a GL_INTEL_performance_queries extension supported by recent Intel drivers on Windows on Sandybridge hardware. Currently (2011-11-05) it appears to be completely undocumented, so I couldn't resist the temptation to work out what it does and how to use it.

Be very careful when using this extension. There's probably a reason why it's not officially documented – it may be buggy or unstable, or may change incompatibly in the future, so don't rely on it continuing to work. Also, this documentation may be wrong.

API

Check for the GL_INTEL_performance_queries extension string, and load the functions with the standard extension mechanism. The argument names and enum names here are just made up by me and probably not highly accurate.

void glGetFirstPerfQueryIdINTEL (GLuint *queryId);

void glGetNextPerfQueryIdINTEL (GLuint prevQueryId, GLuint *queryId);

void glGetPerfQueryInfoINTEL (GLuint queryId,
    GLuint nameMaxLength, char *name,
    GLuint *counterBufferSize, GLuint *numCounters, GLuint *maxQueries,
    GLuint *unknown);

void glGetPerfCounterInfoINTEL (GLuint queryId, GLuint counterId,
    GLuint nameMaxLength, char *name,
    GLuint descMaxLength, char *desc,
    GLuint *offset, GLuint *size, GLuint *usage, GLuint *type,
    GLuint64 *unknown);

void glCreatePerfQueryINTEL (GLuint queryId, GLuint *id);

void glBeginPerfQueryINTEL (GLuint id);

void glEndPerfQueryINTEL (GLuint id);

void glDeletePerfQueryINTEL (GLuint id);

void glGetPerfQueryDataINTEL (GLuint id, GLenum requestType,
    GLuint maxLength, char *buffer, GLuint *length);

#define INTEL_PERFQUERIES_NONBLOCK  0x83FA
#define INTEL_PERFQUERIES_BLOCK     0x83FB

#define INTEL_PERFQUERIES_TYPE_UNSIGNED_INT    0x9402
#define INTEL_PERFQUERIES_TYPE_UNSIGNED_INT64  0x9403
#define INTEL_PERFQUERIES_TYPE_FLOAT           0x9404
#define INTEL_PERFQUERIES_TYPE_BOOL            0x9406

#define INTEL_PERFQUERIES_CATEGORY_MISC1             0x9407
#define INTEL_PERFQUERIES_CATEGORY_TIMEFRACTION      0x9408
#define INTEL_PERFQUERIES_CATEGORY_CYCLESPERTHREAD   0x9409
#define INTEL_PERFQUERIES_CATEGORY_THROUGHPUT        0x940A
#define INTEL_PERFQUERIES_CATEGORY_MISC2             0x940B

Concepts

The implementation supports a number of query types. Each query type is associated with a number of counter types. An application can create query objects (each having some query type), then begin the query, do some rendering, end the query, and (some time in the future) read back the query data. That data contains values for every counter type associated with that query type.

Queries are asynchronous (as with GL_ARB_timer_query) – they are run somewhere deep in the rendering pipeline, not on the CPU. E.g. the TotalTime counter seemingly gives the time taken for the GPU to execute the rendering commands that were sent during the query period, rather than the CPU time taken to submit those rendering commands.

Usage

To find the supported query types, walk it like a linked list:

GLuint queryId;
glGetFirstPerfQueryIdINTEL(&queryId);
while (queryId != 0)
{
    ProcessQueryType(queryId);

    glGetNextPerfQueryIdINTEL(queryId, &queryId);
}

To find the details of a query type (repeat for each queryId):

char queryName[256]; // don't know what the upper limit should be
GLuint bufferSize;
GLuint numCounters;
GLuint maxQueries;
GLuint unknown; // don't know what this is for; always seems to be set to 1

glGetPerfQueryInfoINTEL(queryId, sizeof(queryName), queryName,
    &bufferSize, &numCounters, &maxQueries, &unknown);

To find the counter types for a query type, following on from the above:

for (GLuint counterId = 1; counterId <= numCounters; ++counterId)
{
    char counterName[256];  // don't know what the upper limit should be
    char counterDesc[1024]; // don't know what the upper limit should be
    GLuint counterOffset;
    GLuint counterSize;
    GLuint counterCategory;   // one of INTEL_PERFQUERIES_CATEGORY_*
    GLuint counterType;       // one of INTEL_PERFQUERIES_TYPE_*
    GLuint64 unknown2; // don't know what this is for; seems to be set to 0 or 1

    glGetPerfCounterInfoINTEL(queryId, counterId,
        sizeof(counterName), counterName,
        sizeof(counterDesc), counterDesc,
        &counterOffset, &counterSize, &counterCategory, &counterType, &unknown2);

    ProcessCounterType(...);
}

To perform a query:

GLuint ids[2];
glCreatePerfQueryINTEL(queryId, &ids[0]);
glCreatePerfQueryINTEL(queryId, &ids[1]);
    // you can create up to 'maxQueries' simultaneously for each query type

glBeginPerfQueryINTEL(ids[0]);
// ... do some rendering ...
glEndPerfQueryINTEL(ids[0]);

glBeginPerfQueryINTEL(ids[1]);
// ... do some more rendering ...
glEndPerfQueryINTEL(ids[1]);

// Wait a while - it might take a frame or two before the results are available.

// Request the query data, without blocking if the results aren't available yet:

GLuint length;
char* buffer = (char*) malloc(bufferSize);
glGetPerfQueryDataINTEL(ids[0], INTEL_PERFQUERIES_NONBLOCK, bufferSize, buffer, &length);
if (length == 0)
{
    // results not available yet - should try again later
}
else
{
    assert(length == bufferSize); // always seems to be true
    ParseCounterValues(buffer);
}

// Alternatively you can do a blocking request (it'll do a spinloop until the
// results are available):

glGetPerfQueryDataINTEL(ids[1], INTEL_PERFQUERIES_BLOCK, bufferSize, buffer, &length);
assert(length == bufferSize); // always seems to be true
ParseCounterValues(buffer);

// You can reuse the query objects for subsequent frames,
// or just destroy them at the end:

glDeletePerfQueryINTEL(ids[0]);
glDeletePerfQueryINTEL(ids[1]);

Query results can become available in an arbitrary order. (You can't assume that an earlier query is ready, just because a later query of the same type is ready.)

To parse the counter values, implement the earlier ProcessCounterType like:

switch (counterType)
{
    case INTEL_PERFQUERIES_TYPE_UNSIGNED_INT:
    {
        GLuint value;
        assert(counterSize == sizeof(value));
        memcpy(&value + counterOffset, buffer, sizeof(value));
        // do something with 'value'
        break;
    }
    case INTEL_PERFQUERIES_TYPE_UNSIGNED_INT64:
    {
        GLuint64 value;
        assert(counterSize == sizeof(value));
        memcpy(&value + counterOffset, buffer, sizeof(value));
        // do something with 'value'
        break;
    }
    case INTEL_PERFQUERIES_TYPE_FLOAT:
    {
        GLfloat value;
        assert(counterSize == sizeof(value));
        memcpy(&value + counterOffset, buffer, sizeof(value));
        // do something with 'value'
        break;
    }
    case INTEL_PERFQUERIES_TYPE_BOOL:
    {
        GLuint value;
        assert(counterSize == sizeof(value));
        memcpy(&value + counterOffset, buffer, sizeof(value));
        assert(value == 0 || value == 1);
        // do something with 'value'
        break;
    }
}

Example queries/counters

The following is the list of two queries and many counters reported by an Intel(R) HD Graphics 3000 with driver version 8.15.10.2509 on 64-bit Win7.

Intel_GT_Hardware_Counters (queryId=0x0206, bufferSize=216, maxQueries=32767)

Intel_Pipeline_Query (queryId=0x0104, bufferSize=48, maxQueries=8191)