Package-level declarations

Types

Link copied to clipboard

The default playback device, fed with 32-bit float stereo frames at sampleRate by an AudioRenderer. SDL converts to whatever the hardware wants and follows changes of the default device by itself.

Link copied to clipboard
class AudioException(message: String, cause: Throwable? = null) : KlyphException

Thrown when audio data cannot be decoded or a sound file cannot be opened. The message gives the decoder's reason, or names the file when a loader wraps an earlier AudioException as cause.

Link copied to clipboard
fun interface AudioRenderer

Produces audio for an AudioDevice. klyph's mixer implements it.

Link copied to clipboard

Decoded audio: frameCount frames of 32-bit float samples, each frame holding one value per channel, played at sampleRate frames per second. Samples are nominally in -1..1.

Link copied to clipboard

How a pipeline combines its output with what is already in the color target.

Link copied to clipboard

What a GpuBuffer is bound as.

Link copied to clipboard
value class Color(val rgba: UInt)

An RGBA color with 8 bits per channel, packed as 0xRRGGBBAA.

Link copied to clipboard
value class CommandBuffer

One frame's recorded GPU work. Acquire with GpuDevice.acquireCommandBuffer and finish with submit.

Link copied to clipboard
class CompiledShader(val stage: ShaderStage, msl: String, spirvBase64: String, dxilBase64: String, val samplers: Int, val storageTextures: Int, val storageBuffers: Int, val uniformBuffers: Int)

One shader compiled for every backend: MSL source for Metal, SPIR-V for Vulkan and DXIL for Direct3D 12, with the resource counts SDL needs. Produced by the compileShaders build task from HLSL; create the backend's shader with GpuDevice.createShader.

Link copied to clipboard
value class CopyPass

A copy pass that is being recorded. Uploads go here, before any render pass of the frame.

Link copied to clipboard

Whether the mouse cursor is drawn over a Window.

Link copied to clipboard
enum Cycle : Enum<Cycle>

Whether a map or upload may hand out fresh memory when the previous contents are still in use by the GPU. Cycling avoids a stall but discards the old contents.

Link copied to clipboard

Drains SDL's event queue. Owns one native event record, so polling allocates nothing beyond the returned PlatformEvent. close it when the pump is no longer needed, before Sdl.quit.

Link copied to clipboard

Thrown when a file cannot be read or written. The message names the file and repeats the reason SDL gives.

Link copied to clipboard
object Files

Reads and writes whole files on disk. Relative paths resolve against basePath, the directory that holds the running executable, so assets shipped next to the game are found wherever it is started from. Absolute paths are used as given.

Link copied to clipboard

A frame read back from the GPU for the captures queued with Window.capture. Recorded by CommandBuffer.recordCaptureOrNull into the frame's command buffer; once that buffer has been submitted and its fence waited on, save writes the PNG files and frees the read-back memory.

Link copied to clipboard
value class GamepadAxis(val index: Int)

A gamepad axis in SDL's standard layout: the two sticks and the two analog triggers.

Link copied to clipboard
value class GamepadButton(val index: Int)

A gamepad button in SDL's standard layout, named by position rather than by label: SOUTH is the bottom face button, A on an Xbox pad and cross on a PlayStation pad.

Link copied to clipboard
value class GamepadId(val value: UInt)

Identifies a connected gamepad for as long as it stays connected. SDL never reuses an id, so a gamepad that is unplugged and plugged back in gets a new one.

Link copied to clipboard
value class GpuBuffer

A buffer in GPU memory. Fill it through a TransferBuffer and a CopyPass.

Link copied to clipboard

A GPU device. Create one with the GpuDevice factory, claim a window to present into, and close it after releasing every window and GPU resource created from it.

Link copied to clipboard
value class GpuFence

Signals when submitted GPU work completes. Obtain from CommandBuffer.submitAndAcquireFence.

Link copied to clipboard
value class GpuShader

A compiled shader stage.

Link copied to clipboard
value class GpuTexture

A texture owned by the GPU. Swapchain textures are valid only for the frame they were acquired in; created textures live until GpuDevice.release.

Link copied to clipboard

Whether the GPU backend runs its validation layer. Validation reports API misuse at a large performance cost, so enable it in development builds only.

Link copied to clipboard
value class GraphicsPipeline

A graphics pipeline: shaders plus fixed-function state, for triangle lists without vertex buffers. Vertex data is pulled from storage buffers by vertex index.

Link copied to clipboard
class Image(val width: Int, val height: Int)

A width by height grid of RGBA pixels with 8 bits per channel, stored row by row from the top-left corner. Every pixel starts as transparent black.

Link copied to clipboard
class ImageException(message: String, cause: Throwable? = null) : KlyphException

Thrown when image data cannot be decoded or encoded. The message gives the decoder's reason, or names the file when a loader wraps an earlier ImageException as cause.

Link copied to clipboard
value class KeyCode(val code: UInt)

A keyboard key, identified by SDL's key code.

Link copied to clipboard
@RequiresOptIn(message = "Engine plumbing outside the 1.0 compatibility promise; it may change in any release.", level = RequiresOptIn.Level.ERROR)
annotation class KlyphPlatformApi

Marks the platform plumbing that the klyph engine is built on: the SDL_GPU wrappers, the event pump, the audio device and its renderer, SDL start-up and shutdown, window creation, compiled shaders and frame capture.

Link copied to clipboard
value class MappedFloats

Mapped transfer-buffer memory, addressed as 32-bit floats. Valid until GpuDevice.unmap. The setters inline to plain stores, so filling a buffer allocates nothing.

Link copied to clipboard
value class MouseButton(val index: Int)

A mouse button, numbered from zero: LEFT is 0 and X2 is 4.

Link copied to clipboard
sealed class PlatformEvent

An event taken from the platform's event queue by EventPump.pollOrNull.

Link copied to clipboard

How frames are handed to the display.

Link copied to clipboard
value class RenderPass

A render pass that is being recorded. Call end before recording anything else.

Link copied to clipboard
value class Sampler

Sampling state for textures: filtering and addressing.

Link copied to clipboard

How a sampler reads a texture at texture coordinates outside the range from 0 to 1, where 0 is the texture's left or top edge and 1 its right or bottom edge, on both axes. A sprite meets such coordinates when it repeats one texture across an area larger than the texture.

Link copied to clipboard

How a sampler picks texels when a texture is scaled.

Link copied to clipboard
value class Scancode(val code: UInt)

A physical key position on the keyboard, identified by SDL's scancode.

Link copied to clipboard
object Sdl

Process-wide SDL lifecycle. SDL itself is global, so this is the one place the platform layer exposes that fact.

Link copied to clipboard

Thrown when an SDL call fails. The message names the call and repeats SDL's own error text.

Link copied to clipboard

Compiled shader formats a GpuDevice can consume. Which one is used depends on the backend SDL picks: SPIR-V for Vulkan, DXIL for Direct3D 12, MSL for Metal.

Link copied to clipboard

Pipeline stage a GpuShader runs in.

Link copied to clipboard

Parts of SDL that Sdl.init can start.

Link copied to clipboard
value class TextureFormat

Pixel format of a GPU texture, as chosen by SDL for a swapchain or requested for a created texture.

Link copied to clipboard

What a created texture is used for.

Link copied to clipboard
value class TransferBuffer

CPU-visible staging memory used to move data to the GPU. Map it, write, unmap, then upload in a CopyPass.

Link copied to clipboard

Decodes an Ogg Vorbis file held in memory a block at a time, for music that is too long to decode up front. Open one with VorbisStream.open, pull interleaved float frames with read, start over with rewind, and close it to free the decoder.

Link copied to clipboard

An operating-system window. Create one with the Window factory and close it when done.

Link copied to clipboard

Options a Window is created with.

Link copied to clipboard

How a Window takes up the screen.

Functions

Link copied to clipboard

Waits for the next swapchain texture of window and returns it, or null when the window cannot be drawn to right now, such as while it is minimized. The texture is valid until this command buffer is submitted.

Link copied to clipboard

Begins a copy pass for uploads.

Link copied to clipboard

Begins a render pass that clears target to clearColor and keeps whatever is drawn into it.

Link copied to clipboard

Makes pipeline current for the draws that follow.

Link copied to clipboard
fun RenderPass.bindFragmentSampler(slot: Int, texture: GpuTexture, sampler: Sampler)

Binds texture with sampler as fragment sampler slot.

Link copied to clipboard

Binds buffer as vertex storage buffer slot.

Link copied to clipboard
fun Color(red: Float, green: Float, blue: Float, alpha: Float = 1.0f): Color

Creates a Color from channels in 0.0..1.0. Values outside that range are rejected.

Link copied to clipboard
fun Image.copyFrom(image: Image, x: Int, y: Int, sourceX: Int = 0, sourceY: Int = 0, sourceWidth: Int = image.width - sourceX, sourceHeight: Int = image.height - sourceY)

Copies image, or the rectangle of it sourceWidth pixels wide and sourceHeight pixels tall whose top-left corner is at column sourceX and row sourceY, into this image with that corner at column x and row y. Texels are written as given, alpha included and nothing blended, so a transparent or half-transparent pixel replaces the one under it; draw is the call that blends.

Link copied to clipboard
fun GpuDevice.createBuffer(usage: BufferUsage, sizeInBytes: Int): GpuBuffer

Creates a buffer of sizeInBytes bytes for usage.

Link copied to clipboard

Creates a pipeline drawing triangle lists with vertex and fragment into a single color target of colorFormat, blended with blend. No vertex buffers: vertex data is pulled from storage buffers by vertex index.

Link copied to clipboard
fun GpuDevice.createSampler(filter: SamplerFilter, address: SamplerAddress = SamplerAddress.CLAMP): Sampler

Creates a sampler using filter for both minification and magnification, with texture coordinates outside the texture handled as address says, on both axes of a 2D texture.

Link copied to clipboard

Creates the backend's shader from shader, picking the format this device supports.

fun GpuDevice.createShader(code: ByteArray, format: ShaderFormat, stage: ShaderStage, entryPoint: String, samplers: Int = 0, storageTextures: Int = 0, storageBuffers: Int = 0, uniformBuffers: Int = 0): GpuShader

Creates a shader for stage from code in format. The resource counts must match what the shader declares, or binding at draw time fails. Pass the Int counts by name.

Link copied to clipboard

Creates an RGBA8 texture of the size of image for sampling and uploads its pixels.

fun GpuDevice.createTexture(width: Int, height: Int, format: TextureFormat = TextureFormat.RGBA8, usage: TextureUsage = TextureUsage.SAMPLED): GpuTexture

Creates a 2D texture of width by height texels in format for usage.

Link copied to clipboard

Creates an upload staging buffer of sizeInBytes bytes.

Link copied to clipboard
fun RenderPass.draw(vertexCount: Int, firstVertex: Int = 0)

Draws vertexCount vertices starting at firstVertex with the bound pipeline. Pass the Int parameters by name.

fun Image.draw(image: Image, x: Int, y: Int, sourceX: Int = 0, sourceY: Int = 0, sourceWidth: Int = image.width - sourceX, sourceHeight: Int = image.height - sourceY)

Draws image, or the rectangle of it sourceWidth pixels wide and sourceHeight pixels tall whose top-left corner is at column sourceX and row sourceY, over this image with that corner at column x and row y, blending each of its pixels by its alpha.

Link copied to clipboard
fun Image.drawLine(x1: Int, y1: Int, x2: Int, y2: Int, color: Color)

Sets the pixels of a line one pixel wide from column x1 and row y1 to column x2 and row y2 to color, alpha included, as Image.set does. Nothing is blended, so a transparent color clears the pixels the line covers.

Link copied to clipboard
fun Image.fill(color: Color)

Sets every pixel to color.

Link copied to clipboard
fun Image.fillCircle(centerX: Float, centerY: Float, radius: Float, color: Color)

Paints a disc of radius pixels centered on (centerX, centerY) in color, over what the image already holds.

Link copied to clipboard
fun Image.fillRect(x: Int, y: Int, width: Int, height: Int, color: Color)

Sets every pixel of the rectangle width pixels wide and height pixels tall whose top-left corner is at column x and row y to color, alpha included, as Image.set does. Nothing is blended, so a transparent color clears the rectangle; Image.draw is the call that blends.

Link copied to clipboard
fun GpuDevice(shaderFormats: Set<ShaderFormat>, validation: GpuValidation = GpuValidation.DISABLED): GpuDevice

Creates a GPU device that accepts shaders in any of shaderFormats. Pass every format you ship so SDL can pick a backend on each platform.

Link copied to clipboard
fun Color.lerp(to: Color, t: Float): Color

Returns the color t of the way from this color to to, blending each channel, alpha included, on its own: this color at 0, to at 1. t is clamped to 0.0..1.0, because a blend past either end could leave a channel's range.

Link copied to clipboard

Maps buffer for writing and returns its memory as floats. Call unmap before uploading.

Link copied to clipboard
fun printError(message: String)

Writes message and a line break to the standard error stream and flushes it, for warnings that should not mix with a program's normal output on standard output.

Link copied to clipboard

Copies floats into vertex uniform slot for the draws that follow. Sizes are limited by the backend; a 4x4 matrix is always fine.

Link copied to clipboard
fun CommandBuffer.recordCaptureOrNull(device: GpuDevice, window: Window, texture: GpuTexture, width: Int, height: Int, format: TextureFormat): FrameCapture?

Records a read-back of texture into this command buffer if window has captures queued with Window.capture, and returns it, or returns null and records nothing when none is queued. Takes the queued captures off window either way.

Link copied to clipboard

Frees buffer. Work already submitted may still read it; SDL defers the actual release.

Frees fence.

Frees shader. Pipelines built from it keep working.

Frees texture. Never call this on a swapchain texture.

Frees pipeline.

fun GpuDevice.release(sampler: Sampler)

Frees sampler.

Frees buffer.

Link copied to clipboard
fun Image.save(path: String)

Writes this image to the file at path as a PNG file with four 8-bit channels, creating the file or replacing its contents. Image.decode reads it back pixel for pixel.

Link copied to clipboard

Returns the scancode of the key that types this key code under the current keyboard layout, or Scancode.UNKNOWN when no key on the layout produces it.

Link copied to clipboard

Ends a mapping started with map. The MappedFloats handed out is invalid afterwards.

Link copied to clipboard
fun CopyPass.uploadToBuffer(source: TransferBuffer, destination: GpuBuffer, sizeInBytes: Int, cycle: Cycle, sourceOffset: Int = 0, destinationOffset: Int = 0)

Copies sizeInBytes bytes from source at sourceOffset into destination at destinationOffset. Pass the Int parameters by name.

Link copied to clipboard
fun GpuDevice.uploadToTexture(texture: GpuTexture, image: Image, x: Int, y: Int)

Copies the pixels of image into texture as given, alpha included and nothing blended, with the image's top-left corner at texel x, y, and leaves the rest of texture as it was. The image must lie inside texture, an RGBA8 texture; SDL does not check it.

fun CopyPass.uploadToTexture(source: TransferBuffer, destination: GpuTexture, width: Int, height: Int, sourceOffset: Int = 0, x: Int = 0, y: Int = 0)

Copies tightly packed texels for a width by height rectangle from source at sourceOffset into destination, with the rectangle's top-left corner at texel x, y of destination. With x and y at 0 and the texture's own size it fills the whole texture. The rectangle must lie inside destination; SDL does not check it. Pass the Int parameters after the first pair by name.

Link copied to clipboard

Blocks until the work behind fence has finished on the GPU.

Link copied to clipboard
fun Window(title: String, width: Int, height: Int, flags: Set<WindowFlag> = emptySet()): Window

Creates a window titled title with a client area of width by height points. Both sizes must be positive.

Link copied to clipboard
fun Color.withAlpha(alpha: Float): Color

Returns this color with its alpha channel replaced by alpha, in 0.0..1.0, and red, green and blue unchanged. color.withAlpha(0f) is the color fully transparent, which is what a fade out ends on.

Link copied to clipboard
fun GpuDevice.write(buffer: TransferBuffer, bytes: ByteArray, offset: Int = 0)

Copies bytes into buffer at byte offset. Convenient for one-off uploads such as texture pixels; per-frame data should be written through map instead to avoid the extra copy.