mcap/modules/Capture_File/module.jai

// .mcap: one capture in one file. A fixed magic, a file version stamp, the capture's Capture Text,
// a small preview, then the images. See docs/mcap.md for the layout.
//
// Reading gives views into the bytes it was given; nothing is copied. Images stay PNG.

MCAP_MAGIC     :: u8.[0x89, #char "M", #char "C", #char "A", #char "P", 0x0D, 0x0A, 0x1A];
MCAP_VERSION   :: 1;
MCAP_EXTENSION :: "mcap";
MCAP_PREVIEW_MAX_SIDE :: 320;   // the preview's longest side, in pixels

Mcap_Rendered_Kind :: enum u8 {
  NONE             :: 0;
  SAME_AS_ORIGINAL :: 1;   // the rendered image is byte for byte the original, so it is stored once
  OWN              :: 2;
}

Mcap_Image :: struct {
  width:  u16;
  height: u16;
  png: [] u8;   // empty when there is none
}

Mcap :: struct {
  version: u32 = MCAP_VERSION;   // as read; always MCAP_VERSION when written
  text: string;                  // Capture Text
  preview: Mcap_Image;
  original_name: string;         // the original image's name in the .snagx, such as {GUID}.png
  original: [] u8;               // PNG
  rendered_kind: Mcap_Rendered_Kind;
  rendered: [] u8;               // PNG; OWN only, see mcap_rendered
}

// The rendered image (Snagit's thumbnail.png) whichever way it is stored; empty when there is none.
mcap_rendered :: (m: Mcap) -> [] u8 {
  if m.rendered_kind == {
    case .SAME_AS_ORIGINAL;  return m.original;
    case .OWN;               return m.rendered;
  }
  return .[];
}

// ---------------------------------------------------------------- writing

// The file's bytes. A part too large for its size field fails the whole file rather than writing one
// that cannot be read back.
mcap_serialize :: (m: Mcap) -> Serializer, ok: bool, error: string {
  size := MCAP_HEADER_SIZE + 4 + m.text.count + 8 + m.preview.png.count + 2 + m.original_name.count + 4 + m.original.count + 1;
  if m.rendered_kind == .OWN  size += 4 + m.rendered.count;
  s := new_serializer(size);

  magic := MCAP_MAGIC;
  AddArray_NoSize(*s, magic);
  Add(*s, cast(u32) MCAP_VERSION);

  if !AddString(*s, m.text, u32)  return s, false, "the text is too large for its size field";
  Add(*s, m.preview.width);
  Add(*s, m.preview.height);
  if !AddSizedArray(*s, m.preview.png, u32)  return s, false, "the preview is too large for its size field";
  if !AddString(*s, m.original_name, u16)  return s, false, "the original image's name is too long";
  if !AddSizedArray(*s, m.original, u32)  return s, false, "the original image is too large for its size field";
  Add(*s, m.rendered_kind);
  if m.rendered_kind == .OWN && !AddSizedArray(*s, m.rendered, u32)  return s, false, "the rendered image is too large for its size field";

  assert(s.count == size);
  return s, true, "";
}

// Writes beside path and then swaps it in, so a failure leaves any earlier file as it was.
mcap_write :: (path: string, bytes: [] u8) -> ok: bool, error: string {
  temp_path := tprint("%.tmp", path);
  if !write_entire_file(temp_path, bytes.data, bytes.count)  return false, tprint("cannot write %", temp_path);
  if !atomic_file_replace_or_just_rename_if_destination_file_does_not_exist(temp_path, path) {
    file_delete(temp_path);
    return false, tprint("cannot move % to %", temp_path, path);
  }
  return true, "";
}

// ---------------------------------------------------------------- reading

// A whole .mcap. The parts are views into data. Exactly the file's bytes must be consumed.
mcap_parse :: (data: [] u8) -> Mcap, ok: bool, error: string {
  m: Mcap;
  d := to_deserializer(data);
  ok, error := mcap_read_front_part(*d, *m);
  if !ok  return m, false, error;

  m.original_name = ReadSizedString(*d, u16);
  m.original      = ReadSizedArray(*d, u8, u32);
  m.rendered_kind = Read(*d, Mcap_Rendered_Kind);
  if d.ok && m.rendered_kind == .OWN  m.rendered = ReadSizedArray(*d, u8, u32);
  if !d.ok  return m, false, "the file ends early (it is truncated or damaged)";
  if cast(u8) m.rendered_kind > cast(u8) Mcap_Rendered_Kind.OWN  return m, false, tprint("the rendered image is of unknown kind %", cast(u8) m.rendered_kind);
  if d.cursor != d.count  return m, false, tprint("% bytes follow the last part", d.count - d.cursor);
  return m, true, "";
}

// Only the header, text and preview, as a library browser needs them: one read of the start of the
// file, and at most two more when the text or preview runs past it. The images are left unread and
// empty. The parts are views into a buffer from the context allocator.
mcap_read_front :: (path: string) -> Mcap, ok: bool, error: string {
  m: Mcap;
  file, opened := file_open(path, log_errors = false);
  if !opened  return m, false, "cannot be opened";
  defer file_close(*file);
  length, length_ok := file_length(file);
  if !length_ok  return m, false, "cannot be read";

  wanted := min(length, MCAP_FRONT_READ_SIZE);
  for attempt: 1..3 {
    buffer := NewArray(wanted, u8, initialized = false);
    if !file_read(file, buffer.data, wanted) { array_free(buffer); return m, false, "cannot be read"; }

    d := to_deserializer(buffer);
    ok, error := mcap_read_front_part(*d, *m);
    if ok  return m, true, "";
    if d.ok || wanted == length { array_free(buffer); return m, false, error; }   // not a matter of too few bytes

    // Short: the sizes read so far say how much is needed.
    needed := mcap_front_size(buffer);
    array_free(buffer);
    if needed <= wanted || needed > length  return m, false, "the file ends early (it is truncated or damaged)";
    wanted = needed;
    if !file_set_position(file, 0)  return m, false, "cannot be read";
  }
  return m, false, "cannot be read";
}

#scope_module

MCAP_HEADER_SIZE     :: 12;          // magic and version
MCAP_FRONT_READ_SIZE :: 64 * 1024;   // holds the header, text and preview of nearly every capture

// Header, text and preview.
mcap_read_front_part :: (d: *Deserializer, m: *Mcap) -> ok: bool, error: string {
  magic := ReadArrayView(d, MCAP_MAGIC.count, u8);
  if !d.ok  return false, "is not an .mcap file (it is shorter than the magic)";
  for MCAP_MAGIC  if magic[it_index] != it  return false, "is not an .mcap file (its magic is wrong)";
  m.version = Read(d, u32);
  if !d.ok  return false, "the file ends early (it is truncated or damaged)";
  if m.version == 0  return false, "has file version 0, which does not exist";
  if m.version > MCAP_VERSION  return false, tprint("is file version %, but this build reads up to %; it was written by a later version", m.version, MCAP_VERSION);

  m.text           = ReadSizedString(d, u32);
  m.preview.width  = Read(d, u16);
  m.preview.height = Read(d, u16);
  m.preview.png    = ReadSizedArray(d, u8, u32);
  if !d.ok  return false, "the file ends early (it is truncated or damaged)";
  return true, "";
}

// How many bytes the header, text and preview take, as far as the sizes in prefix tell: with only the
// text's size in it, enough to reach the preview's size; with that too, the whole front.
mcap_front_size :: (prefix: [] u8) -> s64 {
  d := to_deserializer(prefix);
  d.cursor = MCAP_HEADER_SIZE;
  text_size := cast(s64) Read(*d, u32);
  preview_header := MCAP_HEADER_SIZE + 4 + text_size + 4;   // where the preview's size is
  if !d.ok || preview_header + 4 > prefix.count  return preview_header + 4;
  d.cursor = preview_header;
  return preview_header + 4 + cast(s64) Read(*d, u32);
}

#import "Basic";
#import "File";
#import "File_Utilities";
#import "Serialization";