Metadata Overview
You can use the metadata API to attach extra information to named entities or other objects like tracks and track groups. Metadata can be attached to an specific entity by ID, or to the current entity within a given scope (e.g. marker scope, task scope, track scope).
Conceptually, metadata has a type (what kind of metadata), a key (the name of the metadata), and a value (the actual data). The encoding of the value depends on the type of the metadata.
The type of metadata is specified by an enumerated type __itt_metadata_type.
A classic use of metadata is to drill into outlier behavior on a particular task. For example, we might observe that a particular frame buffer-blending task is unusually high. To understand why, we would add metadata to the task that describe the frame-buffer format, and any other run-time state that influences the blending operation:
__itt_string_handle* pH1 = __itt_string_handle_create(L”Drawcall_BlendToFramebuffer”);
__itt_string_handle* pH2 = __itt_string_handle_create(L”PixelPos”);
__itt_string_handle* pH3 = __itt_string_handle_create(L”ColorMask”);
__itt_string_handle* pH4 = __itt_string_handle_create(L”BlendFunc”);
void DrawCall_BlendToFramebuffer(RenderState* rs, Pixel* p)
{
__itt_task_begin(domain, itt_null, itt_null, pH1);
…
int pixel_pos[2] = { p->x, p->y };
__itt_metadata_add(domain, __itt_null, pH2, __itt_metadata_s32, 2, (void*)pixel_pos);
__itt_metadata_add(domain, __itt_null, pH3, __itt_metadata_u32, 1, (void*)&rs->RenderTarget.ColorMask);
__itt_metadata_str_add(domain, __itt_null, pH4, (void*)(rs->RenderTarget.BlendFunc == BLEND_ADD ? “Additive” : “Unknown”), 0);
…
__itt_task_end(domain);
}
The __itt_metadata_add_with_scope and __itt_metadata_str_add_with_scope functions enable you to attach metadata to an object that is implicitly identified within a given scope, rather than having to specify an ID for the object.
See Also
__itt_metadata_add
__itt_metadata_str_add
__itt_scope
__itt_metadata_type
__itt_metadata_add_with_scope
__itt_metadata_str_add_with_scope