context.h

Go to the documentation of this file.

/* BSD 3-Clause License
 *
 * Copyright © 2008-2026, Jice and the libtcod contributors.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived from
 *    this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
#pragma once
#ifndef LIBTCOD_CONTEXT_H_
#define LIBTCOD_CONTEXT_H_
 
#ifdef __cplusplus
#include <algorithm>
#include <array>
#include <memory>
#include <stdexcept>
 
#include "console_types.hpp"
#include "error.hpp"
#endif  // __cplusplus
 
#include "config.h"
#include "console.h"
#include "context_viewport.h"
#include "error.h"
#include "mouse_types.h"
#include "tileset.h"
 
struct SDL_Window;
struct SDL_Renderer;
struct SDL_Rect;
union SDL_Event;
 
struct TCOD_Context;  // Defined in this header later.
typedef struct TCOD_Context TCOD_Context;

typedef struct TCOD_ContextParams {
  int tcod_version;

  int window_x, window_y;
  int pixel_width, pixel_height;
  int columns, rows;
  int renderer_type;
  TCOD_Tileset* tileset;
  int vsync;
  int sdl_window_flags;
  const char* window_title;
  int argc;
  const char* const* argv;
  void (*cli_output)(void* userdata, const char* output);
  void* cli_userdata;
  bool window_xy_defined;

  TCOD_Console* console;
} TCOD_ContextParams;
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
TCOD_PUBLIC void TCOD_context_delete(struct TCOD_Context* renderer);
TCOD_NODISCARD struct TCOD_Context* TCOD_context_new_(void);
TCOD_PUBLIC TCOD_Error TCOD_context_present(
    struct TCOD_Context* context, const struct TCOD_Console* console, const struct TCOD_ViewportOptions* viewport);
TCOD_PUBLIC TCOD_Error TCOD_context_screen_pixel_to_tile_d(struct TCOD_Context* context, double* x, double* y);
TCOD_PUBLIC TCOD_Error TCOD_context_screen_pixel_to_tile_i(struct TCOD_Context* context, int* x, int* y);
TCOD_PUBLIC TCOD_Error TCOD_context_convert_event_coordinates(struct TCOD_Context* context, union SDL_Event* event);
TCOD_PUBLIC TCOD_Error TCOD_context_save_screenshot(struct TCOD_Context* context, const char* filename);
TCOD_PUBLIC struct SDL_Window* TCOD_context_get_sdl_window(struct TCOD_Context* context);
TCOD_PUBLIC struct SDL_Renderer* TCOD_context_get_sdl_renderer(struct TCOD_Context* context);
TCOD_PUBLIC TCOD_Error TCOD_context_change_tileset(struct TCOD_Context* self, TCOD_Tileset* tileset);
TCOD_PUBLIC int TCOD_context_get_renderer_type(struct TCOD_Context* context);
TCOD_PUBLIC TCOD_Error TCOD_context_recommended_console_size(
    struct TCOD_Context* context, float magnification, int* __restrict columns, int* __restrict rows);

TCOD_PUBLIC TCOD_Error TCOD_context_screen_capture(
    struct TCOD_Context* __restrict context,
    TCOD_ColorRGBA* __restrict out_pixels,
    int* __restrict width,
    int* __restrict height);

TCOD_NODISCARD
TCOD_PUBLIC TCOD_ColorRGBA* TCOD_context_screen_capture_alloc(
    struct TCOD_Context* __restrict context, int* __restrict width, int* __restrict height);

TCOD_PUBLIC TCOD_Error TCOD_context_set_mouse_transform(
    struct TCOD_Context* __restrict context, const TCOD_MouseTransform* __restrict transform);
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
struct TCOD_Context {
#ifdef __cplusplus
  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] auto
  get_renderer_type() noexcept -> int {
    return TCOD_context_get_renderer_type(this);
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] void
  present(const TCOD_Console& console, const TCOD_ViewportOptions& viewport) {
    tcod::check_throw_error(TCOD_context_present(this, &console, &viewport));
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] void
  present(const TCOD_Console& console) {
    tcod::check_throw_error(TCOD_context_present(this, &console, nullptr));
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] auto
  get_sdl_window() noexcept -> struct SDL_Window* {
    return TCOD_context_get_sdl_window(this);
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] auto
  get_sdl_renderer() noexcept -> struct SDL_Renderer* {
    return TCOD_context_get_sdl_renderer(this);
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] auto
  pixel_to_tile_coordinates(const std::array<int, 2>& xy) -> std::array<int, 2> {
    std::array<int, 2> out{xy[0], xy[1]};
    tcod::check_throw_error(TCOD_context_screen_pixel_to_tile_i(this, &out[0], &out[1]));
    return out;
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] auto
  pixel_to_tile_coordinates(const std::array<double, 2>& xy) -> std::array<double, 2> {
    std::array<double, 2> out{xy[0], xy[1]};
    tcod::check_throw_error(TCOD_context_screen_pixel_to_tile_d(this, &out[0], &out[1]));
    return out;
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] void
  convert_event_coordinates(SDL_Event& event) {
    tcod::check_throw_error(TCOD_context_convert_event_coordinates(this, &event));
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] void
  save_screenshot(const char* filepath) {
    tcod::check_throw_error(TCOD_context_save_screenshot(this, filepath));
  }

  [[deprecated(
      "TCOD_Context methods have been moved to tcod::Context,"
      " use `auto context = tcod::Context(params);` to make a tcod context for C++.")]] void
  save_screenshot(const std::string& filepath) {
    tcod::check_throw_error(TCOD_context_save_screenshot(this, filepath.c_str()));
  }

  auto new_console(int min_columns = 1, int min_rows = 1, float magnification = 1.0f) -> tcod::Console {
    int columns;
    int rows;
    if (magnification <= 0.0f) {
      throw std::invalid_argument(
          std::string("Magnification must be greater than zero. Got ") + std::to_string(magnification));
    }
    tcod::check_throw_error(TCOD_context_recommended_console_size(this, magnification, &columns, &rows));
    return tcod::Console{std::max(columns, min_columns), std::max(rows, min_rows)};
  }
#endif  // __cplusplus
  // All remaining members are private.
  int type;
  void* __restrict contextdata_;
  // Context C callback are prefixed with 'c_', always check if see if these are NULL.
  void (*c_destructor_)(struct TCOD_Context* __restrict self);
  TCOD_Error (*c_present_)(
      struct TCOD_Context* __restrict self,
      const struct TCOD_Console* __restrict console,
      const struct TCOD_ViewportOptions* __restrict viewport);
  void (*c_pixel_to_tile_)(struct TCOD_Context* __restrict self, double* __restrict x, double* __restrict y);
  TCOD_Error (*c_save_screenshot_)(struct TCOD_Context* __restrict self, const char* __restrict filename);
  struct SDL_Window* (*c_get_sdl_window_)(struct TCOD_Context* __restrict self);
  struct SDL_Renderer* (*c_get_sdl_renderer_)(struct TCOD_Context* __restrict self);
  TCOD_Error (*c_accumulate_)(
      struct TCOD_Context* __restrict self,
      const struct TCOD_Console* __restrict console,
      const struct TCOD_ViewportOptions* __restrict viewport);
  TCOD_Error (*c_set_tileset_)(struct TCOD_Context* __restrict self, TCOD_Tileset* __restrict tileset);
  TCOD_Error (*c_recommended_console_size_)(
      struct TCOD_Context* __restrict self, float magnification, int* __restrict columns, int* __restrict rows);

  TCOD_Error (*c_screen_capture_)(
      struct TCOD_Context* __restrict self,
      TCOD_ColorRGBA* __restrict out_pixels,
      int* __restrict width,
      int* __restrict height);

  TCOD_Error (*c_set_mouse_transform_)(
      struct TCOD_Context* __restrict self, const TCOD_MouseTransform* __restrict transform);
};
#ifdef __cplusplus
namespace tcod {
struct ContextDeleter {
  void operator()(TCOD_Context* console) const { TCOD_context_delete(console); }
};
typedef std::unique_ptr<TCOD_Context, ContextDeleter> ContextPtr;
typedef std::shared_ptr<TCOD_Context> ContextSharedPtr;
}  // namespace tcod
#endif  // __cplusplus
#endif  // LIBTCOD_CONTEXT_H_