tracy.mettle

// Mettle standard library: Tracy profiler
//
// Real-time CPU/frame profiling via the Tracy C API (https://github.com/wolfpld/tracy).
// Requires linking stdlib/tracy_helpers.c and a Tracy client built with TRACY_ENABLE.
//
// Typical Windows profiled build:
//   cl /c /DTRACY_ENABLE /I <tracy>\public stdlib\tracy_helpers.c
//   cl /c /DTRACY_ENABLE /I <tracy>\public <tracy>\public\TracyClient.cpp /TP
//   mettle --build app.mettle -o app.exe ^
//     --link-arg stdlib\tracy_helpers.obj ^
//     --link-arg TracyClient.obj
//
// Without TRACY_ENABLE, tracy_helpers.c compiles to no-op stubs so the same
// source can be linked in release builds.
//
// Zone usage (end zones with defer for LIFO cleanup):
//   import "std/tracy";
//   import "std/io";
//
//   fn work() {
//     var z: TracyZone = tracy_zone_colored(
//       cstr("work"), cstr("app.mettle"), 42, cstr("work"), tracy_color_update());
//     defer tracy_scope_end(z);
//     ...
//   }
//
//   fn main() -> int32 {
//     tracy_plot_setup_number(cstr("frame_ms"), 1, 1, tracy_color_render());
//     while (running != 0) {
//       do_frame();
//       tracy_frame_mark();
//     }
//     return 0;
//   }
//
// See examples/tracy_demo/ for a full demonstrative program.

import "std/conv";
import "std/mem";

// Opaque Tracy zone context (matches ___tracy_c_zone_context / mettle_tracy_zone_t).
export struct TracyZone {
  id: uint32;
  active: int32;
}

// ─── Plot format (TracyPlotFormatEnum) ───────────────────────────────────────
export fn tracy_plot_number() -> int32 { return 0; }
export fn tracy_plot_memory() -> int32 { return 1; }
export fn tracy_plot_percentage() -> int32 { return 2; }
export fn tracy_plot_watt() -> int32 { return 3; }

// ─── Message severity (TracyMessageSeverity) ─────────────────────────────────
export fn tracy_severity_trace() -> int32 { return 0; }
export fn tracy_severity_debug() -> int32 { return 1; }
export fn tracy_severity_info() -> int32 { return 2; }
export fn tracy_severity_warning() -> int32 { return 3; }
export fn tracy_severity_error() -> int32 { return 4; }
export fn tracy_severity_fatal() -> int32 { return 5; }

// ─── Named zone colors (Tracy ABGR) ─────────────────────────────────────────
export fn tracy_color_input() -> uint32 { return 0xFF44AA44; }
export fn tracy_color_update() -> uint32 { return 0xFF4488FF; }
export fn tracy_color_render() -> uint32 { return 0xFF0088FF; }
export fn tracy_color_load() -> uint32 { return 0xFFAA44FF; }
export fn tracy_color_warn() -> uint32 { return 0xFF0044FF; }

// ─── C bridge (stdlib/tracy_helpers.c) ───────────────────────────────────────
export extern fn mettle_tracy_zone_begin(
  line: uint32,
  file: cstring,
  file_len: int64,
  func_name: cstring,
  func_name_len: int64,
  name: cstring,
  name_len: int64,
  color: uint32,
  active: int32,
  out: TracyZone*
) = "mettle_tracy_zone_begin";

export extern fn mettle_tracy_zone_end(zone: TracyZone) = "mettle_tracy_zone_end";
export extern fn mettle_tracy_zone_text(zone: TracyZone, text: cstring, text_len: int64) = "mettle_tracy_zone_text";
export extern fn mettle_tracy_zone_name(zone: TracyZone, text: cstring, text_len: int64) = "mettle_tracy_zone_name";
export extern fn mettle_tracy_zone_color(zone: TracyZone, color: uint32) = "mettle_tracy_zone_color";
export extern fn mettle_tracy_zone_value(zone: TracyZone, value: uint64) = "mettle_tracy_zone_value";

export extern fn mettle_tracy_frame_mark() = "mettle_tracy_frame_mark";
export extern fn mettle_tracy_frame_mark_named(name: cstring) = "mettle_tracy_frame_mark_named";
export extern fn mettle_tracy_frame_mark_start(name: cstring) = "mettle_tracy_frame_mark_start";
export extern fn mettle_tracy_frame_mark_end(name: cstring) = "mettle_tracy_frame_mark_end";

export extern fn mettle_tracy_set_thread_name(name: cstring) = "mettle_tracy_set_thread_name";

export extern fn mettle_tracy_plot(name: cstring, value: float64) = "mettle_tracy_plot";
export extern fn mettle_tracy_plot_float(name: cstring, value: float32) = "mettle_tracy_plot_float";
export extern fn mettle_tracy_plot_int(name: cstring, value: int64) = "mettle_tracy_plot_int";
export extern fn mettle_tracy_plot_config(name: cstring, type: int32, step: int32, fill: int32, color: uint32) = "mettle_tracy_plot_config";

export extern fn mettle_tracy_message(text: cstring, text_len: int64) = "mettle_tracy_message";
export extern fn mettle_tracy_message_colored(text: cstring, text_len: int64, color: uint32) = "mettle_tracy_message_colored";
export extern fn mettle_tracy_message_literal(text: cstring) = "mettle_tracy_message_literal";
export extern fn mettle_tracy_app_info(text: cstring, text_len: int64) = "mettle_tracy_app_info";

export extern fn mettle_tracy_alloc(ptr: cstring, size: int64) = "mettle_tracy_alloc";
export extern fn mettle_tracy_free(ptr: cstring) = "mettle_tracy_free";

export extern fn mettle_tracy_connected() -> int32 = "mettle_tracy_connected";
export extern fn mettle_tracy_started() -> int32 = "mettle_tracy_started";
export extern fn mettle_tracy_startup() = "mettle_tracy_startup";
export extern fn mettle_tracy_shutdown() = "mettle_tracy_shutdown";

// ─── Zones ───────────────────────────────────────────────────────────────────

// Begin a profiling zone. Pass active=0 to skip instrumentation (e.g. when
// tracy_connected() is 0 under TRACY_ON_DEMAND). name may be 0 for function-only label.
export fn tracy_zone_begin(
  name: cstring,
  file: cstring,
  line: uint32,
  func_name: cstring,
  color: uint32,
  active: int32
) -> TracyZone {
  var z: TracyZone;
  var name_len: int64 = 0;
  if (name != 0) {
    name_len = strlen(name);
  }
  mettle_tracy_zone_begin(
    line,
    file,
    strlen(file),
    func_name,
    strlen(func_name),
    name,
    name_len,
    color,
    active,
    &z
  );
  return z;
}

export fn tracy_zone(
  name: cstring,
  file: cstring,
  line: uint32,
  func_name: cstring
) -> TracyZone {
  return tracy_zone_begin(name, file, line, func_name, 0, 1);
}

export fn tracy_zone_active(
  name: cstring,
  file: cstring,
  line: uint32,
  func_name: cstring,
  active: int32
) -> TracyZone {
  return tracy_zone_begin(name, file, line, func_name, 0, active);
}

export fn tracy_zone_colored(
  name: cstring,
  file: cstring,
  line: uint32,
  func_name: cstring,
  color: uint32
) -> TracyZone {
  return tracy_zone_begin(name, file, line, func_name, color, 1);
}

// Begin a zone only when Tracy is connected (TRACY_ON_DEMAND builds).
export fn tracy_zone_on_demand(
  name: cstring,
  file: cstring,
  line: uint32,
  func_name: cstring,
  color: uint32
) -> TracyZone {
  return tracy_zone_begin(name, file, line, func_name, color, tracy_connected());
}

export fn tracy_zone_end(zone: TracyZone) {
  mettle_tracy_zone_end(zone);
}

// Readable alias for defer tracy_scope_end(z).
export fn tracy_scope_end(zone: TracyZone) {
  tracy_zone_end(zone);
}

export fn tracy_zone_text(zone: TracyZone, text: cstring) {
  if (text == 0) {
    return;
  }
  mettle_tracy_zone_text(zone, text, strlen(text));
}

export fn tracy_zone_name(zone: TracyZone, text: cstring) {
  if (text == 0) {
    return;
  }
  mettle_tracy_zone_name(zone, text, strlen(text));
}

export fn tracy_zone_color(zone: TracyZone, color: uint32) {
  mettle_tracy_zone_color(zone, color);
}

export fn tracy_zone_value(zone: TracyZone, value: uint64) {
  mettle_tracy_zone_value(zone, value);
}

// ─── Frames ──────────────────────────────────────────────────────────────────
export fn tracy_frame_mark() {
  mettle_tracy_frame_mark();
}

export fn tracy_frame_mark_named(name: cstring) {
  mettle_tracy_frame_mark_named(name);
}

export fn tracy_frame_mark_start(name: cstring) {
  mettle_tracy_frame_mark_start(name);
}

export fn tracy_frame_mark_end(name: cstring) {
  mettle_tracy_frame_mark_end(name);
}

// ─── Threads, plots, messages ────────────────────────────────────────────────
export fn tracy_set_thread_name(name: cstring) {
  mettle_tracy_set_thread_name(name);
}

export fn tracy_plot(name: cstring, value: float64) {
  mettle_tracy_plot(name, value);
}

export fn tracy_plot_float(name: cstring, value: float32) {
  mettle_tracy_plot_float(name, value);
}

export fn tracy_plot_int(name: cstring, value: int64) {
  mettle_tracy_plot_int(name, value);
}

export fn tracy_plot_config(name: cstring, type: int32, step: int32, fill: int32, color: uint32) {
  mettle_tracy_plot_config(name, type, step, fill, color);
}

export fn tracy_plot_setup_number(name: cstring, step: int32, fill: int32, color: uint32) {
  tracy_plot_config(name, tracy_plot_number(), step, fill, color);
}

export fn tracy_plot_setup_memory(name: cstring, step: int32, fill: int32, color: uint32) {
  tracy_plot_config(name, tracy_plot_memory(), step, fill, color);
}

export fn tracy_message(text: cstring) {
  if (text == 0) {
    return;
  }
  mettle_tracy_message(text, strlen(text));
}

export fn tracy_message_colored(text: cstring, color: uint32) {
  if (text == 0) {
    return;
  }
  mettle_tracy_message_colored(text, strlen(text), color);
}

export fn tracy_message_literal(text: cstring) {
  mettle_tracy_message_literal(text);
}

export fn tracy_app_info(text: cstring) {
  if (text == 0) {
    return;
  }
  mettle_tracy_app_info(text, strlen(text));
}

// ─── Memory events (custom allocators) ───────────────────────────────────────
export fn tracy_alloc(ptr: cstring, size: int64) {
  mettle_tracy_alloc(ptr, size);
}

export fn tracy_free(ptr: cstring) {
  mettle_tracy_free(ptr);
}

// malloc/free with Tracy memory events for custom-allocator demos.
export fn tracy_malloc(size: int64) -> cstring {
  var p: cstring = malloc(size);
  if (p != 0) {
    tracy_alloc(p, size);
  }
  return p;
}

export fn tracy_heap_free(ptr: cstring) {
  if (ptr != 0) {
    tracy_free(ptr);
    free(ptr);
  }
}

// ─── Connection / manual lifetime ────────────────────────────────────────────
export fn tracy_connected() -> int32 {
  return mettle_tracy_connected();
}

export fn tracy_started() -> int32 {
  return mettle_tracy_started();
}

export fn tracy_startup() {
  mettle_tracy_startup();
}

export fn tracy_shutdown() {
  mettle_tracy_shutdown();
}