Clock Domain API
================
Some applications require the capability to trace events with user-defined
timestamps and frequencies that are different from the ones generated by a
CPU. For example, you may want to instrument events that occur on a GPU.
To do this, you can create a clock domain.
To create a clock domain, use this following primitive:
.. code:: cpp
__itt_clock_domain * ITTAPI __itt_clock_domain_create(__itt_get_clock_info_fn fn, void* fn_data)
**Parameters of the primitive:**
+-------+-------------+-------------------------------------------------------------+
| [in] | ``fn`` | Pointer to a callback function that retrieves alternative |
| | | CPU timestamps and frequencies and stores them in the |
| | | clock domain structure field ``__itt_clock_info``. |
+-------+-------------+-------------------------------------------------------------+
| [in] | ``fn_data`` | Argument passed to the callback function. Can be ``NULL``. |
+-------+-------------+-------------------------------------------------------------+
Tasks issued from different clock domains display on the same timeline. This
happens by the synchronization of a referenced clock domain base timestamp
(captured at the instant when the clock domain was created) and a CPU timestamp
(captured in the same instant).
To recalculate clock domain base timestamps and frequencies, if necessary,
for example, when a GPU frequency changes, use the following primitive:
.. code:: cpp
__itt_clock_domain_reset()
