platform.h File Reference

This file contains the platform layer, or at least the interface to it. Each platform should provide its own implementation of this in a .c file, and should be compiled exclusively of the rest. More...

#include "defines.h"
#include "input_types.h"
#include "logger.h"

Go to the source code of this file.

Data Structures
struct	platform_system_config
struct	dynamic_library_function
struct	dynamic_library
struct	kwindow_config
	A configuration structure used to create new windows. More...
struct	kwindow
	Represents a window in the application. More...

Typedefs
typedef struct platform_system_config	platform_system_config
typedef struct dynamic_library_function	dynamic_library_function
typedef struct dynamic_library	dynamic_library
typedef enum platform_error_code	platform_error_code
typedef struct kwindow_config	kwindow_config
	A configuration structure used to create new windows. More...
typedef struct kwindow	kwindow
	Represents a window in the application. More...
typedef void(*	platform_filewatcher_file_deleted_callback) (u32 watcher_id, void *context)
typedef void(*	platform_filewatcher_file_written_callback) (u32 watcher_id, const char *file_path, b8 is_binary, void *context)
typedef void(*	platform_window_closed_callback) (const struct kwindow *window)
typedef void(*	platform_window_resized_callback) (const struct kwindow *window)
typedef void(*	platform_process_key) (keys key, b8 pressed)
typedef void(*	platform_process_mouse_button) (mouse_buttons button, b8 pressed)
typedef void(*	platform_process_mouse_move) (i16 x, i16 y)
typedef void(*	platform_process_mouse_wheel) (i8 z_delta)

Enumerations
enum	platform_error_code {   PLATFORM_ERROR_SUCCESS = 0 , PLATFORM_ERROR_UNKNOWN = 1 , PLATFORM_ERROR_FILE_NOT_FOUND = 2 , PLATFORM_ERROR_FILE_LOCKED = 3 ,   PLATFORM_ERROR_FILE_EXISTS = 4 }

Functions
KAPI b8	platform_system_startup (u64 *memory_requirement, struct platform_state *state, platform_system_config *config)
	Performs startup routines within the platform layer. Should be called twice, once to obtain the memory requirement (with state=0), then a second time passing an allocated block of memory to state. More...
KAPI void	platform_system_shutdown (struct platform_state *state)
	Shuts down the platform layer. More...
KAPI b8	platform_window_create (const kwindow_config *config, struct kwindow *window, b8 show_immediately)
	Creates a new window from the given config and optionally opens it immediately. More...
KAPI void	platform_window_destroy (struct kwindow *window)
	Destroys the given window. More...
KAPI b8	platform_window_show (struct kwindow *window)
	Shows the given window. Has no effect if the window is already shown. More...
KAPI b8	platform_window_hide (struct kwindow *window)
	Hides the given window. Has no effect if the window is already hidden. Note that this does not destroy the window. More...
KAPI const char *	platform_window_title_get (const struct kwindow *window)
	Obtains the window title from the given window, if it exists. NOTE: Returns a constant copy of the string, which must be freed by the caller. More...
KAPI b8	platform_window_title_set (struct kwindow *window, const char *title)
	Sets the given window's title, if it exists. More...
KAPI b8	platform_pump_messages (void)
	Performs any platform-specific message pumping that is required for windowing, etc. More...
KAPI void *	platform_allocate (u64 size, b8 aligned)
	Performs platform-specific memory allocation of the given size. More...
KAPI void	platform_free (void *block, b8 aligned)
	Frees the given block of memory. More...
KAPI void *	platform_zero_memory (void *block, u64 size)
	Performs platform-specific zeroing out of the given block of memory. More...
KAPI void *	platform_copy_memory (void *dest, const void *source, u64 size)
	Copies the bytes of memory in source to dest, of the given size. More...
KAPI void *	platform_set_memory (void *dest, i32 value, u64 size)
	Sets the bytes of memory to the given value. More...
KAPI void	platform_console_write (struct platform_state *platform, log_level level, const char *message)
	Performs platform-specific printing to the console of the given message and log level. More...
KAPI f64	platform_get_absolute_time (void)
	Gets the absolute time since the application started. More...
KAPI void	platform_sleep (u64 ms)
	Sleep on the thread for the provided milliseconds. This blocks the main thread. Should only be used for giving time back to the OS for unused update power. Therefore it is not exported. Times are approximate. More...
KAPI i32	platform_get_processor_count (void)
	Obtains the number of logical processor cores. More...
KAPI void	platform_get_handle_info (u64 *out_size, void *memory)
	Obtains the required memory amount for platform-specific handle data, and optionally obtains a copy of that data. Call twice, once with memory=0 to obtain size, then a second time where memory = allocated block. More...
KAPI f32	platform_device_pixel_ratio (const struct kwindow *window)
	Returns the device pixel ratio of the supplied window. More...
KAPI b8	platform_dynamic_library_load (const char *name, dynamic_library *out_library)
	Loads a dynamic library. More...
KAPI b8	platform_dynamic_library_unload (dynamic_library *library)
	Unloads the given dynamic library. More...
KAPI void *	platform_dynamic_library_load_function (const char *name, dynamic_library *library)
	Loads an exported function of the given name from the provided loaded library. More...
KAPI const char *	platform_dynamic_library_extension (void)
	Returns the file extension for the current platform. More...
KAPI const char *	platform_dynamic_library_prefix (void)
	Returns a file prefix for libraries for the current platform. More...
KAPI platform_error_code	platform_copy_file (const char *source, const char *dest, b8 overwrite_if_exists)
	Copies file at source to destination, optionally overwriting. More...
KAPI void	platform_register_window_closed_callback (platform_window_closed_callback callback)
	Registers the system-level handler for a window being closed. More...
KAPI void	platform_register_window_resized_callback (platform_window_resized_callback callback)
	Registers the system-level handler for a window being resized. More...
KAPI void	platform_register_process_key (platform_process_key callback)
	Registers the system-level handler for a keyboard key being pressed. More...
KAPI void	platform_register_process_mouse_button_callback (platform_process_mouse_button callback)
	Registers the system-level handler for a mouse button being pressed. More...
KAPI void	platform_register_process_mouse_move_callback (platform_process_mouse_move callback)
	Registers the system-level handler for a mouse being moved. More...
KAPI void	platform_register_process_mouse_wheel_callback (platform_process_mouse_wheel callback)
	Registers the system-level handler for a mouse wheel being scrolled. More...
KAPI b8	platform_watch_file (const char *file_path, b8 is_binary, platform_filewatcher_file_written_callback watcher_written_callback, void *watcher_written_context, platform_filewatcher_file_deleted_callback watcher_deleted_callback, void *watcher_deleted_context, u32 *out_watch_id)
	Watch a file at the given path. More...
KAPI b8	platform_unwatch_file (u32 watch_id)
	Stops watching the file with the given watch identifier. More...

Detailed Description

This file contains the platform layer, or at least the interface to it. Each platform should provide its own implementation of this in a .c file, and should be compiled exclusively of the rest.

Author

Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version

2.0

Date

2022-01-10

Copyright

Kohi Game Engine is Copyright (c) Travis Vroman 2021-2024

Typedef Documentation

dynamic_library

typedef struct dynamic_library dynamic_library

dynamic_library_function

typedef struct dynamic_library_function dynamic_library_function

kwindow

typedef struct kwindow kwindow

Represents a window in the application.

kwindow_config

typedef struct kwindow_config kwindow_config

A configuration structure used to create new windows.

platform_error_code

typedef enum platform_error_code platform_error_code

platform_filewatcher_file_deleted_callback

typedef void(* platform_filewatcher_file_deleted_callback) (u32 watcher_id, void *context)

platform_filewatcher_file_written_callback

typedef void(* platform_filewatcher_file_written_callback) (u32 watcher_id, const char *file_path, b8 is_binary, void *context)

platform_process_key

typedef void(* platform_process_key) (keys key, b8 pressed)

platform_process_mouse_button

typedef void(* platform_process_mouse_button) (mouse_buttons button, b8 pressed)

platform_process_mouse_move

typedef void(* platform_process_mouse_move) (i16 x, i16 y)

platform_process_mouse_wheel

typedef void(* platform_process_mouse_wheel) (i8 z_delta)

platform_system_config

typedef struct platform_system_config platform_system_config

platform_window_closed_callback

typedef void(* platform_window_closed_callback) (const struct kwindow *window)

platform_window_resized_callback

typedef void(* platform_window_resized_callback) (const struct kwindow *window)

Enumeration Type Documentation

platform_error_code

enum platform_error_code

Enumerator
PLATFORM_ERROR_SUCCESS
PLATFORM_ERROR_UNKNOWN
PLATFORM_ERROR_FILE_NOT_FOUND
PLATFORM_ERROR_FILE_LOCKED
PLATFORM_ERROR_FILE_EXISTS

Function Documentation

platform_allocate()

KAPI void* platform_allocate	(	u64	size,
		b8	aligned
	)

Performs platform-specific memory allocation of the given size.

Parameters

size	The size of the allocation in bytes.
aligned	Indicates if the allocation should be aligned.

Returns

A pointer to a block of allocated memory.

platform_console_write()

KAPI void platform_console_write	(	struct platform_state *	platform,
		log_level	level,
		const char *	message
	)

Performs platform-specific printing to the console of the given message and log level.

Parameters

platform	A pointer to the platform state.
message	The message to be printed.
colour	The colour to print the text in (if supported).

platform_copy_file()

KAPI platform_error_code platform_copy_file	(	const char *	source,
		const char *	dest,
		b8	overwrite_if_exists
	)

Copies file at source to destination, optionally overwriting.

Parameters

source	The source file path.
dest	The destination file path.
overwrite_if_exists	Indicates if the file should be overwritten if it exists.

Returns

An error code indicating success or failure.

platform_copy_memory()

KAPI void* platform_copy_memory	(	void *	dest,
		const void *	source,
		u64	size
	)

Copies the bytes of memory in source to dest, of the given size.

Parameters

dest	The destination memory block.
source	The source memory block.
size	The size of data to be copied.

Returns

A pointer to the destination block of memory.

platform_device_pixel_ratio()

KAPI f32 platform_device_pixel_ratio

(

const struct kwindow *

window

)

Returns the device pixel ratio of the supplied window.

Parameters

window

A constant pointer to the window to retrieve device pixel ratio for.

Returns

The device pixel ratio.

platform_dynamic_library_extension()

KAPI const char* platform_dynamic_library_extension

(

void

)

Returns the file extension for the current platform.

platform_dynamic_library_load()

KAPI b8 platform_dynamic_library_load	(	const char *	name,
		dynamic_library *	out_library
	)

Loads a dynamic library.

Parameters

name	The name of the library file, excluding the extension. Required.
out_library	A pointer to hold the loaded library. Required.

Returns

True on success; otherwise false.

platform_dynamic_library_load_function()

KAPI void* platform_dynamic_library_load_function	(	const char *	name,
		dynamic_library *	library
	)

Loads an exported function of the given name from the provided loaded library.

Parameters

name	The function name to be loaded.
library	A pointer to the library to load the function from.

Returns

A pointer to the loaded function if it exists; otherwise 0/null.

platform_dynamic_library_prefix()

KAPI const char* platform_dynamic_library_prefix

(

void

)

Returns a file prefix for libraries for the current platform.

platform_dynamic_library_unload()

KAPI b8 platform_dynamic_library_unload

(

dynamic_library *

library

)

Unloads the given dynamic library.

Parameters

library

A pointer to the loaded library. Required.

Returns

True on success; otherwise false.

platform_free()

KAPI void platform_free	(	void *	block,
		b8	aligned
	)

Frees the given block of memory.

Parameters

block	The block to be freed.
aligned	Indicates if the block of memory is aligned.

platform_get_absolute_time()

KAPI f64 platform_get_absolute_time

(

void

)

Gets the absolute time since the application started.

Returns

The absolute time since the application started.

platform_get_handle_info()

KAPI void platform_get_handle_info	(	u64 *	out_size,
		void *	memory
	)

Obtains the required memory amount for platform-specific handle data, and optionally obtains a copy of that data. Call twice, once with memory=0 to obtain size, then a second time where memory = allocated block.

Parameters

out_size	A pointer to hold the memory requirement.
memory	Allocated block of memory.

platform_get_processor_count()

KAPI i32 platform_get_processor_count

(

void

)

Obtains the number of logical processor cores.

Returns

The number of logical processor cores.

platform_pump_messages()

KAPI b8 platform_pump_messages

(

void

)

Performs any platform-specific message pumping that is required for windowing, etc.

Returns

True on success; otherwise false.

platform_register_process_key()

KAPI void platform_register_process_key

(

platform_process_key

callback

)

Registers the system-level handler for a keyboard key being pressed.

Parameters

callback

A pointer to the handler function.

Returns

KAPI

platform_register_process_mouse_button_callback()

KAPI void platform_register_process_mouse_button_callback

(

platform_process_mouse_button

callback

)

Registers the system-level handler for a mouse button being pressed.

Parameters

callback

A pointer to the handler function.

platform_register_process_mouse_move_callback()

KAPI void platform_register_process_mouse_move_callback

(

platform_process_mouse_move

callback

)

Registers the system-level handler for a mouse being moved.

Parameters

callback

A pointer to the handler function.

platform_register_process_mouse_wheel_callback()

KAPI void platform_register_process_mouse_wheel_callback

(

platform_process_mouse_wheel

callback

)

Registers the system-level handler for a mouse wheel being scrolled.

Parameters

callback

A pointer to the handler function.

platform_register_window_closed_callback()

KAPI void platform_register_window_closed_callback

(

platform_window_closed_callback

callback

)

Registers the system-level handler for a window being closed.

Parameters

callback

A pointer to the handler function.

platform_register_window_resized_callback()

KAPI void platform_register_window_resized_callback

(

platform_window_resized_callback

callback

)

Registers the system-level handler for a window being resized.

Parameters

callback

A pointer to the handler function.

platform_set_memory()

KAPI void* platform_set_memory	(	void *	dest,
		i32	value,
		u64	size
	)

Sets the bytes of memory to the given value.

Parameters

dest	The destination block of memory.
value	The value to be set.
size	The size of data to set.

Returns

A pointer to the set block of memory.

platform_sleep()

KAPI void platform_sleep

(

u64

ms

)

Sleep on the thread for the provided milliseconds. This blocks the main thread. Should only be used for giving time back to the OS for unused update power. Therefore it is not exported. Times are approximate.

Parameters

ms	The number of milliseconds to sleep for.

platform_system_shutdown()

KAPI void platform_system_shutdown

(

struct platform_state *

state

)

Shuts down the platform layer.

Parameters

state

A pointer to the platform layer state.

platform_system_startup()

KAPI b8 platform_system_startup	(	u64 *	memory_requirement,
		struct platform_state *	state,
		platform_system_config *	config
	)

Performs startup routines within the platform layer. Should be called twice, once to obtain the memory requirement (with state=0), then a second time passing an allocated block of memory to state.

Parameters

memory_requirement	A pointer to hold the memory requirement in bytes.
state	A pointer to a block of memory to hold state. If obtaining memory requirement only, pass 0.
config	A pointer to a configuration platform_system_config structure required by this system.

Returns

True on success; otherwise false.

platform_unwatch_file()

KAPI b8 platform_unwatch_file

(

u32

watch_id

)

Stops watching the file with the given watch identifier.

Parameters

watch_id

The watch identifier

Returns

True on success; otherwise false.

platform_watch_file()

KAPI b8 platform_watch_file	(	const char *	file_path,
		b8	is_binary,
		platform_filewatcher_file_written_callback	watcher_written_callback,
		void *	watcher_written_context,
		platform_filewatcher_file_deleted_callback	watcher_deleted_callback,
		void *	watcher_deleted_context,
		u32 *	out_watch_id
	)

Watch a file at the given path.

Parameters

file_path	The file path. Required.
is_binary	Indicates if the file being watched is binary (if not, then text).
watcher_written_callback	Callback to be invoked when the watched file is written to.
watcher_written_context	Context to be passed along when a file write occurs.
watcher_deleted_callback	Callback to be invoked when the watched file is deleted from disk.
watcher_deleted_context	Context to be passed along when a file deletion occurs.
out_watch_id	A pointer to hold the watch identifier.

Returns

True on success; otherwise false.

platform_window_create()

KAPI b8 platform_window_create	(	const kwindow_config *	config,
		struct kwindow *	window,
		b8	show_immediately
	)

Creates a new window from the given config and optionally opens it immediately.

Parameters

config	A constant pointer to the configuration to be used for creating the window.
window	A pointer to hold the newly-created window.
show_immediately	Indicates whether the window should open immediately upon creation.

Returns

b8 True on success; otherwise false.

platform_window_destroy()

KAPI void platform_window_destroy

(

struct kwindow *

window

)

Destroys the given window.

Parameters

window

A pointer to the window to be destroyed.

platform_window_hide()

KAPI b8 platform_window_hide

(

struct kwindow *

window

)

Hides the given window. Has no effect if the window is already hidden. Note that this does not destroy the window.

Parameters

window

A pointer to the window to be hidden.

Returns

b8 True on success; otherwise false.

platform_window_show()

KAPI b8 platform_window_show

(

struct kwindow *

window

)

Shows the given window. Has no effect if the window is already shown.

Parameters

window

A pointer to the window to be shown.

Returns

b8 True on success; otherwise false.

platform_window_title_get()

KAPI const char* platform_window_title_get

(

const struct kwindow *

window

)

Obtains the window title from the given window, if it exists. NOTE: Returns a constant copy of the string, which must be freed by the caller.

Parameters

window

A pointer to the window whose title to get.

Returns

A constant copy of the window's title, or 0 if there is no title or the window doesn't exist.

platform_window_title_set()

KAPI b8 platform_window_title_set	(	struct kwindow *	window,
		const char *	title
	)

Sets the given window's title, if it exists.

Parameters

window	A pointer to the window whose title is to be set.
title	The title to be set.

Returns

KAPI True on success; otherwise false.

platform_zero_memory()

KAPI void* platform_zero_memory	(	void *	block,
		u64	size
	)

Performs platform-specific zeroing out of the given block of memory.

Parameters

block	The block to be zeroed out.
size	The size of data to zero out.

Returns

A pointer to the zeroed out block of memory.