MappTrace

This function creates a trace marker or section that allows runtime events to be easily identified in a trace log. Add a trace marker or section at places in your code that need attention, such as before entering and/or just after existing an external event or block of code. You can create a trace log using Matrox Profiler, or by calling MappControl() with M_TRACE set to M_LOG_ENABLE. See the Matrox Profiler and trace logs section of Chapter 31: Development and debugging tools and techniques for more information on creating a trace log.

When creating a trace marker, only a single function call to MappTrace() is needed (TraceType set to M_TRACE_MARKER). When creating a trace section, two calls to MappTrace() are needed, one function call to start the section and another call to end the section (TraceType set to M_TRACE_SECTION_START and M_TRACE_SECTION_END, respectively).

When creating a trace marker or section, you can assign it a trace tag (TraceTag), a trace value (TraceValue), and/or a trace string (TraceString). The trace tag is a fixed user-defined value that identifies the trace marker or section. The trace value and trace string are used to display information relevant to the current placement of the marker; typically, these are variables that depend on runtime events, such as the calculated or return value of a user-defined function. When reading a trace log with Matrox Profiler, you can directly search for your trace markers or sections and display the relevant information. Note that when creating a trace section, both calls to MappTrace() must have the same TraceTag value.

Optionally, this function can set additional trace tag information using TraceType set to M_TRACE_SET_TAG_INFORMATION. Once this additional tag information is set, all trace markers or sections that have the same TraceTag value will use the trace tag's color and name. When viewing an .mtrace file in Matrox Profiler, trace markers and sections display this new tag information, along with the original trace values and trace strings assigned when the trace marker or section was created. Together, these pieces of information add an extra level of convenience when searching for trace markers or sections.

Note that MappTrace() does nothing if you are not generating a trace log.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

ContextAppId

Specifies the identifier of the application context to use.

For specifying the application context
Value	Description
M_DEFAULT	Specifies the current application context.
Application context identifier	Specifies the application context identifier.

TraceType

Specifies the type of trace marker to create.

For specifying the trace type
Value	Description
M_DEFAULT	Same as M_TRACE_MARKER.
M_TRACE_MARKER	Specifies to create a trace marker that identifies a single point in the code.
M_TRACE_SECTION_END	Specifies to end a user trace section. It must come after M_TRACE_SECTION_START, and must have the same TraceTag value as the corresponding start. (summarize) Specifies to end a user trace section. (more details...)
M_TRACE_SECTION_START	Specifies to start a user trace section. It must be followed by a call to MappTrace() with M_TRACE_SECTION_END. (summarize) Specifies to start a user trace section. (more details...)
M_TRACE_SET_TAG_INFORMATION	Specifies to associate a name and/or color with the specified trace tag. Trace markers or sections that have the same tag will display this color an/or name in Matrox Profiler. Associating a color allows the user to quickly identify different trace markers or sections instead of seeing the same color for all user traces in Matrox Profiler. Associating a name to a marker or section can be helpful in searching for the marker's or section's name rather than its numerical TraceTag value. Note that when generating a trace log in memory, the color and name associated with a trace tag will not display. (summarize) Specifies to associate a name and/or color with the specified trace tag. (more details...)

TraceTag

Specifies a value that identifies this trace marker or section.

For specifying the trace tag
Value	Description
M_NULL	Specifies that no trace tag is used for this trace marker or section.
1 <= Value <= 255	Specifies a user-defined value. When using Matrox Profiler, you can search for a marker or section based on its TraceTag value. When creating a trace section, both the start function call and the end function call must specify the same TraceTag value. When TraceType is set to M_TRACE_SET_TAG_INFORMATION, this value specifies the trace tag to apply the tag information to. All trace markers and sections with the same trace tag display the tag's color and/or name. (summarize) Specifies a user-defined value. (more details...)

TraceValue

Specifies a value relevant to the trace marker or section, or relevant to the surrounding code.

For specifying the trace value
Value	Description
M_NULL	Specifies that no trace value is logged for this trace marker or section.
Value	Specifies a user-defined value.

When TraceType is set to M_TRACE_SET_TAG_INFORMATION, you can specify a color associated with the trace tag.

For specifying the trace color
Value	Description
M_DEFAULT	Specifies the default color.
M_RGB888( MIL_INT Red, MIL_INT Green, MIL_INT Blue )	Specifies an RGB value used to clear an 8-bit 3-band buffer to an RGB color. Each value (red, green or blue) must not exceed 8 bits. (summarize) Specifies an RGB value used to clear an 8-bit 3-band buffer to an RGB color. (more details...)
		Parameters
		Red Specifies the red component, as a value between 0 and 255.
		Green Specifies the green component, as a value between 0 and 255.
		Blue Specifies the blue component, as a value between 0 and 255.

TraceString

Specifies a string relevant to the trace marker or section, or relevant to the surrounding code.

For specifying the trace string
Value	Description
M_NULL	Specifies that no trace string is logged for this trace marker or section.
MIL_TEXT("TraceString") ¹	Specifies a user-defined string.

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

When TraceType is set to M_TRACE_SET_TAG_INFORMATION, you can specify a name associated with the trace tag.

For specifying the trace name
Value	Description
MIL_TEXT("M_DEFAULT") ¹	Specifies the default name, which is equivalent to the value of the TraceTag parameter.
MIL_TEXT("TraceTagName") ¹	Specifies a user-defined name for the trace tag.

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.