api.txt

==========================================================================
=== Graphics =============================================================
==========================================================================

  // color format: 0xAARRGGBB

  set_pixel(x, y, color)
  line(x0, y0, x1, y1, color)
  rect(x, y, width, height, color)
  fill_rect(x, y, width, height, color)
  circle(x, y, radius, color)
  fill_circle(x, y, radius, color)
  polygon(points_array, color)
  fill_convex_polygon(points_array, color)

  set_font_name(font_name)  // set_font_name("mono"), set_font_name("sans"), set_font_name("*.ttf")
  set_font_size(size_px)

  text_out(x, y, text, color)
  get_text_size(text)

  get_current_font_name()
  get_current_font_size()

--------------------------------------------------------------------------

  get_screen_width(): int
  get_screen_height(): int

--------------------------------------------------------------------------

  enable_premultiplied_alpha_blend()
  enable_alpha_blend()
  disable_alpha_blend()

--------------------------------------------------------------------------

class Image

  //
  // This class stores the image itself.
  // If you need a link to the image to pass it to functions, use "ImageHandler" instead.
  //

  var img: Image
  var img <- create_image(width, height)
  var img <- create_image("file_name")  // .png .jpg .tga
  var img <- create_image(width, height, [{uint[] 0xFF000000; 0xFF002042 ... }])
  var img <- create_image(width, height, ".ABC", {{ '.' => 0x0; 'A' => 0xFFA0AFFF; 'B' => 0xFFFFFFFF }})

  img.valid
  img.width
  img.height

  img |> set_pixel(x, y, color)
  img |> get_pixel(x, y)
  img |> set_image_data([[uint[] 0xFF000000; 0xFF002042; ... ]])
  img |> get_image_data(data)  // var data: array<uint>; data.resize(img.width * img.height)

  img |> premultiply_alpha()
  img |> make_image_color_transparent(img |> get_pixel(0, 0))

  img |> set_image_smooth(true)  // set filter to 'linear'
  img |> set_image_clamp(true)   // true - 'clamp', false - repeat
  img |> set_image_use_mipmap()  // generate mipmap

  img |> flip_image_x()
  img |> flip_image_y()

  img2 := img // clone
  delete img

--------------------------------------------------------------------------

  img |> draw_image(x, y)
  img |> draw_image(x, y, color)
  img |> draw_image(x, y, color, size: float)
  img |> draw_image(x, y, color, size: float2)

  img |> draw_image_region(x, y, texture_rect: float4)  // texture_rect - float4(x, y, width, height) in texels
  img |> draw_image_region(x, y, texture_rect: float4, color)
  img |> draw_image_region(x, y, texture_rect: float4, color, size: float)
  img |> draw_image_region(x, y, texture_rect: float4, color, size: float2)

  img |> draw_image_transformed(x, y, texture_rect: float4, color, size: float2, angle, relative_pivot_x, relative_pivot_y)
  img |> draw_image_transformed(x, y, texture_rect: float4, color, size: float2, angle)  // pivot at center (0.5, 0.5)

  img |> draw_quad(float2(0, 0), float2(0, 64), float2(64, 64), float2(64, 0), color)
  img |> draw_quad(array_of_float2, color)

  img |> draw_triangle_strip(coords, texture_coords)
  img |> draw_triangle_strip(coords, texture_coords, color)
  img |> draw_triangle_strip(coords, texture_coords, colors)


--------------------------------------------------------------------------

class ImageHandle

  //
  // This lightweight class can be used to conveniently transfer images to various functions,
  // or store links to pictures in tables.
  //

  create_managed_image(file_name: string; smooth: bool = false; use_mips: bool = false): ImageHandle
  create_managed_image(width, height: int; smooth: bool = false; use_mips: bool = false): ImageHandle
  create_managed_image(width, height: int; pixels: array<uint> &; smooth: bool = false; use_mips: bool = false): ImageHandle
  create_managed_image(width, height: int; pixels: string; palette): ImageHandle
  
  var image_handle: ImageHandle

  image_handle.width
  image_handle.height

  clone_managed_image(image_handle: ImageHandle): ImageHandle
  delete_managed_image(image_handle: ImageHandle)
  move_to_managed_storage(var image: Image &): ImageHandle
  clone_to_managed_storage(image: Image): ImageHandle

  image_handle |> draw_image_transformed(x, y, texture_rect, color, size, angle, relative_pivot_x, relative_pivot_y)
  image_handle |> draw_image_transformed(x, y, texture_rect, color, size, angle)
  image_handle |> draw_image(x, y)
  image_handle |> draw_image(x, y, color)
  image_handle |> draw_image(x, y, color, size)
  image_handle |> draw_image_region(x, y, texture_rect)
  image_handle |> draw_image_region(x, y, texture_rect, color)
  image_handle |> draw_image_region(x, y, texture_rect, color, size)
  image_handle |> draw_quad(p0, p1, p2, p3)
  image_handle |> draw_quad(p0, p1, p2, p3, color)
  image_handle |> draw_triangle_strip(coords, texture_coords)
  image_handle |> draw_triangle_strip(coords, texture_coords, colors)
  image_handle |> set_pixel(x, y, color)
  image_handle |> get_pixel(x, y)
  image_handle |> set_image_data(data)
  image_handle |> get_image_data(data)
  image_handle |> premultiply_alpha()
  image_handle |> make_image_color_transparent(color)
  image_handle |> set_image_smooth(is_smooth)
  image_handle |> set_image_clamp(is_clamp)
  image_handle |> set_image_use_mipmap()
  image_handle |> flip_image_x()
  image_handle |> flip_image_y()


--------------------------------------------------------------------------

class Mesh      // 2D

  var mesh <- create_mesh_triangles(positions, tex_coords, colors, indices)
  var mesh <- create_mesh_triangles(positions, tex_coords, indices)
  var mesh <- create_mesh_triangles(positions, indices)

  var mesh <- create_mesh_triangle_strip(positions, tex_coords, colors, indices)
  var mesh <- create_mesh_triangle_strip(positions, tex_coords, indices)
  var mesh <- create_mesh_triangle_strip(positions, indices)

  mesh |> draw_mesh(texture_image, x, y, angle, scale)   // angle - radians, scale - float or float2
  mesh |> draw_mesh(x, y, angle, scale)


--------------------------------------------------------------------------

  make_color(brightness: float): uint
  make_color(brightness, alpha: float): uint
  make_color(r, g, b: float): uint
  make_color(r, g, b, a: float): uint
  make_color(c: float3): uint
  make_color(c: float4): uint

  make_color32(r, g, b: int): uint
  make_color32(r, g, b, a: int): uint
  make_color32(r, g, b: uint): uint
  make_color32(r, g, b, a: uint): uint

  color_to_float4(c: uint): float4
  color_to_float3(c: uint): float3

  premultiply_color(c: uint): uint
  desaturate_color(c: uint): uint
  multiply_colors(c1, c2: uint): uint
  add_colors(c1, c2: uint): uint
  lerp_colors(a, b: uint; t: float): uint


--------------------------------------------------------------------------

  setup_2d_camera(center)
  setup_2d_camera(center, scale)

  // default camera: setup_2d_camera(float2(get_screen_width() / 2, get_screen_height() / 2), 1.0)


--------------------------------------------------------------------------

  transform2d_reset()
  transform2d_push()
  transform2d_pop()
  transform2d_translate(offset)
  transform2d_translate(offset_x, offset_y)
  transform2d_scale(scale, center)
  transform2d_scale(scale)
  transform2d_rotate(angle)
  transform2d_rotate(angle, center)


--------------------------------------------------------------------------

  // get local coordinates after functions setup_2d_camera and transform2d_*

  screen_to_world(point): float2
  screen_to_world(x, y): float2
  world_to_screen(point): float2
  world_to_screen(x, y): float2


==========================================================================
=== Input ================================================================
==========================================================================

  get_key(key_code)
  get_key_down(key_code)
  get_key_up(key_code)
  get_key_press(key_code)
  var unicode_symbol: uint = fetch_entered_symbol()

  get_mouse_button(mouse_button)
  get_mouse_button_down(MB_LEFT)
  get_mouse_button_up(MB_LEFT)
  get_mouse_scroll_delta(): float
  get_mouse_position(): float2
  get_mouse_position_delta()
  get_mouse_velocity()

  set_relative_mouse_mode(is_relative)
  is_relative_mouse_mode()

  show_mouse_cursor()  // don't use with set_relative_mouse_mode()
  hide_mouse_cursor()  // don't use with set_relative_mouse_mode()

  get_axis(axis_code)

  get_key_code(key_name: string): int
  get_key_name(key_code: int): string


  Mouse button codes:

    MB_LEFT
    MB_RIGHT
    MB_MIDDLE


  Keyboard key codes:

    VK_0, VK_1, ...
    VK_A, VK_B, ...
    VK_F1, VK_F2, ...
    VK_NUMPAD0, VK_NUMPAD1, ...

    VK_ESCAPE
    VK_RETURN      // Enter
    VK_SPACE
    VK_LEFT
    VK_RIGHT
    VK_UP
    VK_DOWN
    VK_LSHIFT      // Left Shift
    VK_RSHIFT      // Right Shift
    VK_LCONTROL    // Left Control
    VK_RCONTROL    // Rright Control
    VK_LALT        // Left Alt
    VK_RALT        // Right Alt
    VK_LSYSTEM     // Left System (Win)
    VK_RSYSTEM     // Right System (Win)
    VK_MENU
    VK_TAB
    VK_HOME
    VK_PRIOR       // PageUp
    VK_END
    VK_NEXT        // PageDown
    VK_INSERT
    VK_DELETE
    VK_TILDE       // ~
    VK_MINUS       // Hyphen
    VK_EQUALS      // =
    VK_BACK        // BackSpace
    VK_LBRACKET    // [
    VK_RBRACKET    // ]
    VK_SEMICOLON   // ;
    VK_APOSTROPHE  // '
    VK_BACKSLASH   // \
    VK_COMMA       // ,
    VK_PERIOD      // .
    VK_SLASH       // /
    VK_DIVIDE      // '/' on Numpad
    VK_MULTIPLY    // '*' on Numpad
    VK_SUBTRACT    // '-' on Numpad
    VK_ADD         // '+' on Numpad
    VK_PAUSE


  Gamepad key codes:

    GP_A
    GP_B
    GP_X
    GP_Y
    GP_LEFT_SHOULDER
    GP_RIGHT_SHOULDER
    GP_BACK
    GP_START
    GP_LEFT_STICK
    GP_RIGHT_STICK


  Gamepad axes codes:

    AXIS_PRIMARY_X
    AXIS_PRIMARY_Y
    AXIS_TRIGGERS
    AXIS_TRIGGERS_2
    AXIS_SECONDARY_X
    AXIS_SECONDARY_Y
    AXIS_POV_X
    AXIS_POV_Y





==========================================================================
=== Sound ================================================================
==========================================================================

class PcmSound

  //
  // This class stores the sound itself.
  // If you need a link to the sound to pass it to functions, use "SoundHandle" instead.
  //

  var snd: PcmSound
  var snd <- create_sound("file_name") // .wav .flac .mp3
  var snd <- create_sound(44100, monoSamples: array<float>)
  var snd <- create_sound(44100, stereoSamples: array<float2>)

  snd.duration     // in seconds
  snd.frequency    // samples per seconds
  snd.samples
  snd.channels
  snd.valid

  snd |> set_sound_data(data)  // data: array<float> or data: array<float2>
  snd |> get_sound_data(data)  // var data: array<float>; data.resize(snd.samples)
  snd |> get_sound_data(data)  // var data: array<float2>; data.resize(snd.samples)

  delete snd


  snd |> play_sound()
  snd |> play_sound(volume)
  snd |> play_sound(volume, pitch)
  snd |> play_sound(volume, pitch, pan)
  snd |> play_sound(volume, pitch, pan, start_time, stop_time)

  snd |> play_sound_loop()
  snd |> play_sound_loop(volume)
  snd |> play_sound_loop(volume, pitch)
  snd |> play_sound_loop(volume, pitch, pan)
  snd |> play_sound_loop(volume, pitch, pan, start_time, stop_time)

  snd |> play_sound_deferred(defer_seconds)
  snd |> play_sound_deferred(defer_seconds, volume)
  snd |> play_sound_deferred(defer_seconds, volume, pitch)
  snd |> play_sound_deferred(defer_seconds, volume, pitch, pan)
  snd |> play_sound_deferred(defer_seconds, volume, pitch, pan, start_time, stop_time)

--------------------------------------------------------------------------

class SoundHandle

  //
  // This lightweight class can be used to conveniently transfer sounds to various functions,
  // or store links to sounds in tables.
  //

  create_managed_sound("file_name"): SoundHandle // .wav .flac .mp3
  create_managed_sound(44100, monoSamples: array<float>): SoundHandle
  create_managed_sound(44100, stereoSamples: array<float2>): SoundHandle

  var sound_handle: SoundHandle

  sound_handle.duration     // in seconds
  sound_handle.frequency    // samples per seconds
  sound_handle.samples
  sound_handle.channels
  sound_handle.valid

  sound_handle |> set_sound_data(data)  // data: array<float> or data: array<float2>
  sound_handle |> get_sound_data(data)  // var data: array<float>; data.resize(snd.samples)
  sound_handle |> get_sound_data(data)  // var data: array<float2>; data.resize(snd.samples)

  delete_managed_sound(sound_handle)
  clone_managed_sound(sound_handle)
  move_to_managed_storage(var sound: PcmSound &): SoundHandle
  clone_to_managed_storage(sound: PcmSound): SoundHandle

  sound_handle |> play_sound()
  sound_handle |> play_sound(volume)
  sound_handle |> play_sound(volume, pitch)
  sound_handle |> play_sound(volume, pitch, pan)
  sound_handle |> play_sound(volume, pitch, pan, start_time, stop_time)

  sound_handle |> play_sound_loop()
  sound_handle |> play_sound_loop(volume)
  sound_handle |> play_sound_loop(volume, pitch)
  sound_handle |> play_sound_loop(volume, pitch, pan)
  sound_handle |> play_sound_loop(volume, pitch, pan, start_time, stop_time)

  sound_handle |> play_sound_deferred(defer_seconds)
  sound_handle |> play_sound_deferred(defer_seconds, volume)
  sound_handle |> play_sound_deferred(defer_seconds, volume, pitch)
  sound_handle |> play_sound_deferred(defer_seconds, volume, pitch, pan)
  sound_handle |> play_sound_deferred(defer_seconds, volume, pitch, pan, start_time, stop_time)


--------------------------------------------------------------------------

  var handle: PlayingSoundHandle = snd |> play_sound...(...)
  var handle = snd |> play_sound...(...)

  is_playing(handle): bool
  get_sound_play_pos(handle): float

  set_sound_volume(handle, volume)  // 1.0 - default volume
  set_sound_pitch(handle, pitch)    // 1.0 - default pitch
  set_sound_pan(handle, pan)        // 0.0 - default pitch  (pan = -1.0..1.0)
  set_sound_play_pos(handle, pos_in_seconds)

  stop_sound(handle)


--------------------------------------------------------------------------

  // output arrays will be resized inside functions

  fft_real_forward(real_signal_input, complex_frequencies_output)  // length if input array (N) must be power of 2
  fft_real_inverse(complex_frequencies_input, real_signal_output)
  fft_calculate_magnitudes(complex_frequencies, magnitudes_output)
  fft_calculate_normalized_magnitudes(complex_frequencies, magnitudes_output)  // maginudes divided by N
  fft_calculate_log_magnitudes(complex_frequencies, log_magnitudes_output)





==========================================================================
=== Utils ================================================================
==========================================================================

  print("x = {x}\n")
  debug(x)
  panic("error_text")

  schedule_pause()          // pause after act() and go to 'Log Screen'
  schedule_quit_game()
  schedule_screenshot(file_name)  // take screenshot after draw()

  is_window_active()

  set_window_title("title")
  set_resolution(1280, 720)
  set_rendering_upscale(1)
  disable_auto_upscale()    // enabled by default
  set_antialiasing(4)       // 0 - disable
  set_vsync_enabled(vsync)  // vertical synchronization is enabled by default

  get_desktop_width(): int
  get_desktop_height(): int
  get_desktop_dpi(): int

  get_time_after_start()    // in seconds
  reset_time_after_start()
  get_delta_time()

  local_storage_set(key, value: string)
  local_storage_get(key: string): string
  local_storage_has_key(key: string): bool





==========================================================================
=== Additional dasbox Math ===============================================
==========================================================================

  sqr(x)
  move_to(from, to, dt, vel)
  approach(from, to, dt, viscosity)
  cvt(value, from_range_1, from_range_2, to_range_1, to_range_2)

  normalize_angle(angle)  // to -PI..PI
  angle_diff(source, target)
  angle_move_to(from, to, dt, vel)
  angle_approach(from, to, dt, viscosity)





==========================================================================
=== daScript Math ========================================================
==========================================================================

  PI

  abs(x)
  sign(x)
  min(a, b)
  max(a, b)
  clamp(value, min_v, max_v)
  saturate(x) = clamp(x, 0.0, 1.0)
  lerp(a, b, t)

  ceil(x)
  floor(x)
  ceili(x): int
  floori(x): int
  roundi(x): int

  sin(x)
  cos(x)
  sincos(x: float const; s: float& implicit; c: float& implicit)
  tan(x)

  asin(x)
  acos(x)
  atan(x)
  atan2(y, x)

  sqrt(x)
  rsqrt(x) = 1.0 / sqrt(x)
  rsqrt_est(x)

  exp(x)
  exp2(x)
  log(x)
  log2(x)
  rcp(x) = 1.0 / x

  is_nan(x)
  is_finite(x)


Noise functions:

  uint32_hash(seed: uint const): uint
  uint_noise_1D(position: int const; seed: uint const): uint
  uint_noise_2D(position: int2 const; seed: uint const): uint
  uint_noise_3D(position: int3 const; seed: uint const): uint


Random numbers:

  random_float(seed: int4& implicit): float
  random_float4(seed: int4& implicit): float4
  random_int(seed: int4& implicit): int
  random_int4(seed: int4& implicit): int4
  random_seed(seed: int const): int4

  random_in_unit_disk(seed: int4& implicit): float3
  random_in_unit_sphere(seed: int4& implicit): float3
  random_unit_vector(seed: int4& implicit): float3

  randomize_seed(seed: int4&)


Only float3:

  cross(x: float3 const; y: float3 const)
  distance(x: float3 const; y: float3 const)
  distance_sq(x: float3 const; y: float3 const)
  inv_distance(x: float3 const; y: float3 const)
  inv_distance_sq(x: float3 const; y: float3 const)
  reflect(v: float3 const; n: float3 const)
  refract(v: float3 const; n: float3 const; nint: float const; outRefracted: float3&)


float2, float3, float4:

  dot(x, y)
  normalize(x)
  fast_normalize(x)
  length(x)
  length_sq(x)
  inv_length(x)
  inv_length_sq(x)
            

Matrix operations:

  float3x4 - floating point matrix with 4 rows and 3 columns
  float4x4 - floating point matrix with 4 rows and 4 columns

  float3x4() - returns empty matrix, where each component is 0
  float4x4() - returns empty matrix, where each component is 0

  == (x: float4x4 const implicit; y: float4x4 const implicit): bool
  != (x: float4x4 const implicit; y: float4x4 const implicit): bool
  *  (x: float3x4 const implicit; y: float3x4 const implicit): float3x4
  *  (x: float4x4 const implicit; y: float4x4 const implicit): float4x4
  *  (x: float3x4 const implicit; y: float3 const) : float3
  *  (x: float4x4 const implicit; y: float4 const) : float4

  identity(x: float3x4 implicit)
  identity(x: float4x4 implicit)

  compose(pos: float4 const; rot: float4 const; scale: float4 const): float4x4
  decompose(mat: float4x4 const implicit; pos: float3& implicit; rot: float4& implicit; scale: float4& implicit): void
  inverse(x: float3x4 const implicit): float3x4
  inverse(m: float4x4 const implicit): float4x4
  look_at(eye: float4 const; at: float4 const; up: float4 const): float4x4
  orthonormal_inverse(m: float4x4 const implicit): float4x4
  persp_forward(wk: float const; hk: float const; zn: float const; zf: float const): float4x4
  persp_reverse(wk: float const; hk: float const; zn: float const; zf: float const): float4x4
  rotate(x: float3x4 const implicit; y: float3 const): float3
  translation(xyz: float3 const): float4x4
  transpose(x: float4x4 const implicit): float4x4


Quaternion operations:

  quat_conjugate(q: float4 const): float4
  quat_mul(q1: float4 const; q2: float4 const): float4
  quat_mul_vec(q: float4 const; v: float3 const): float3
  un_quat(m: float4x4 const implicit): float4
  un_quat_from_unit_arc(v0: float3 const; v1: float3 const): float4
  un_quat_from_unit_vec_ang(v: float3 const; ang: float const): float4