Minor cleanups and better documentation for the spec generation scripts.

[apitrace] / common / trace_format.hpp

diff --git a/common/trace_format.hpp b/common/trace_format.hpp
index a8ee5eb8bab0347ce2a691691783d6c6939f6d22..2a1150c746a63e8fbf668c82918402f52014ecfa 100644 (file)
--- a/common/trace_format.hpp
+++ b/common/trace_format.hpp
@@ -70,9 +70,38 @@
 #ifndef _TRACE_FORMAT_HPP_
 #define _TRACE_FORMAT_HPP_
 
-namespace Trace {
+namespace trace {
 
-#define TRACE_VERSION 1
+/*
+ * Trace file version number.
+ *
+ * We keep backwards compatability reading old traces, i.e., it should always be
+ * possible to parse and retrace old trace files.
+ *
+ * So the trace version number refers not only to changes in the binary format
+ * representation, but also semantic changes in the way certain functions
+ * should be retraced.
+ *
+ * Writing/editing old traces will not be supported however.  An older version
+ * of apitrace should be used in such circunstances.
+ *
+ * Changelog:
+ *
+ * - version 0:
+ *   - initial implementation
+ *
+ * - version 1:
+ *   - support for GL user arrays -- a blob is provided whenever an user memory
+ *   is referred (whereas before calls that operate wit user memory instead of
+ *   VBOs should be ignore)
+ *
+ * - version 2:
+ *   - malloc/free memory calls -- allow to pass user memory as malloc memory
+ *   as opposed to blobs
+ *   - glFlushMappedBufferRange will emit a memcpy only for the flushed range
+ *   (whereas previously it would emit a memcpy for the whole mapped range)
+ */
+#define TRACE_VERSION 2
 
 enum Event {
     EVENT_ENTER = 0,
@@ -104,6 +133,6 @@ enum Type {
 };
 
 
-} /* namespace Trace */
+} /* namespace trace */
 
 #endif /* _TRACE_FORMAT_HPP_ */