texel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc746766a443584c97dcf37b69f42f2a77e04337488d1dccd794be408d59da52
+  data.tar.gz: 26d50b5b34ae127a95f62b46c5f1c029d7fdd876013cb62aa12cf6efb9a3328e
+SHA512:
+  metadata.gz: '04686cc60e1595a187297ac36e487e571d300aa363090b1d32de7bd30ada0767cf697602f248b1acd22da8de21269701dfa5a393814b09b2ffab1aac5e2462bf'
+  data.tar.gz: a259720f0efc3eaa8d0928584ce4a0bd84ecec52b6a7d6f3a1d539b5a4d77fb0fad6512d238282bee033e531fc4da72ce8be7ad7ca57eed2d165cdd88400cf98

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,219 @@
+# Texel
+
+Texel is a texture-oriented image I/O library for Ruby. It combines a small C
+extension built from vendored stb headers with a pure Ruby QOI codec, an
+immutable pixel container, color and channel conversion, mipmap generation,
+and WebGPU/OpenGL upload helpers.
+
+Texel intentionally does not provide drawing, compositing, or image filters.
+Its job is the path from encoded image bytes to tightly packed texture data.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- A C99 compiler when installing the source gem
+- No runtime gem or system image-library dependencies
+
+The stb headers are included in the gem. QOI remains usable when a compiler is
+unavailable by setting `TEXEL_DISABLE_NATIVE=1` while installing:
+
+```sh
+TEXEL_DISABLE_NATIVE=1 gem install texel
+ruby your_qoi_program.rb
+```
+
+The environment variable is only required during installation. At runtime,
+Texel detects that the extension is absent and keeps the pure Ruby QOI codec
+available automatically.
+
+This source-gem fallback still requires the platform's `make` command because
+RubyGems invokes it for every declared extension. Precompiled platform gems do
+not require a compiler or `make`.
+
+## Installation
+
+Add Texel to your bundle:
+
+```ruby
+gem "texel", "~> 0.1"
+```
+
+Then run `bundle install`, or install it directly:
+
+```sh
+gem install texel
+```
+
+Release artifacts include precompiled gems for x86-64 and ARM64 Linux,
+Intel and Apple Silicon macOS, and 64-bit UCRT Windows. Each platform gem
+contains extensions for Ruby 3.2, 3.3, 3.4, and 4.0, selected automatically at
+load time. RubyGems falls back to the source gem on other platforms.
+
+## Loading and saving
+
+Texel accepts a path, a readable IO, or an encoded binary String. The format is
+detected from magic bytes, with the file extension used for TGA as a fallback.
+
+```ruby
+require "texel"
+
+image = Texel.load("albedo.png")
+rgba = Texel.load("albedo.jpg", channels: 4)
+floats = Texel.load(File.binread("albedo.png"), dtype: :f32)
+normal = Texel.load("normal.png", color_space: :linear)
+
+metadata = Texel.info("albedo.png")
+# => #<data Texel::Info width=... height=... channels=... format=:png>
+
+Texel.save(rgba, "output.png")
+Texel.save(rgba, "output.jpg", quality: 90)
+encoded = Texel.encode(rgba, :qoi)
+```
+
+`Texel.load_all(paths, threads: 4)` decodes a collection concurrently while
+preserving input order. Native decode and resize operations of at least one
+megapixel release the GVL.
+
+### Formats
+
+| Format | Decode | Encode | Notes |
+|---|---:|---:|---|
+| PNG | yes | yes | u8 and u16 decode |
+| JPEG | yes | yes | `quality:` controls encoding |
+| BMP | yes | yes | lossless |
+| TGA | yes | yes | lossless |
+| GIF | yes | no | first frame only |
+| PSD | yes | no | composite image |
+| HDR/RGBE | yes | yes | defaults to f32/linear |
+| QOI | yes | yes | pure Ruby |
+
+KTX2, EXR, and WebP signatures are recognized. Until their extension gems are
+loaded, Texel raises `Texel::MissingCodecError` with the required gem name.
+
+## Image data
+
+`Texel::Image` stores frozen, tightly packed, top-left-origin pixel data:
+
+```ruby
+image.width          # Integer
+image.height         # Integer
+image.channels       # 1..4
+image.dtype          # :u8, :u16, or :f32
+image.color_space    # :srgb, :linear, or :unknown
+image.data           # frozen ASCII-8BIT String
+image.row_bytes
+image.pixel(0, 0)    # debug-oriented Array access
+```
+
+Frozen binary input is adopted directly; mutable input is copied once to keep
+the container immutable. Native resize and f32-to-f16 conversion write into
+Ruby-owned buffers directly. stb decode and encode require one ownership copy
+because stb allocates their result buffers itself.
+
+Construct images directly with packed data when needed:
+
+```ruby
+image = Texel::Image.new(
+  width: 1,
+  height: 1,
+  channels: 4,
+  dtype: :f32,
+  color_space: :linear,
+  data: [1.0, 0.5, 0.25, 1.0].pack("e*")
+)
+```
+
+The constructor checks dimensions, tags, and the exact data size. Transforming
+methods return new images:
+
+```ruby
+image.flip_y
+image.convert(channels: 4, dtype: :f32)
+image.resize(512, 512, filter: :mitchell)
+image.resize_to_fit(1024)
+image.to_linear
+image.to_srgb
+image.premultiply
+image.unpremultiply
+image.mipmaps
+```
+
+Resize filters are `:box`, `:triangle`, `:cubic`, `:mitchell`, and `:lanczos`.
+sRGB mipmaps are resized in linear space by default; use `mipmaps(fast: true)`
+to resize encoded sRGB values directly.
+
+## WebGPU upload
+
+The optional helper targets the keyword API used by `webgpu-ruby` and handles
+format inference, mip generation, f32-to-f16 conversion, and 256-byte row
+alignment:
+
+```ruby
+require "texel/wgpu"
+
+texture = Texel::WGPU.upload(
+  image,
+  device: device,
+  queue: queue,
+  label: "albedo"
+)
+```
+
+Supported inferred layouts are u8 R/RG/RGBA and f32 R/RG/RGBA. WebGPU has no
+three-channel texture format, so RGB input raises `Texel::FormatError`; convert
+it explicitly with `image.convert(channels: 4)`. `Texel::WGPU.pad_rows` is also
+available when only transfer-buffer preparation is needed.
+
+## OpenGL upload metadata
+
+`texel/gl` returns the internal format, external format, and component type
+without loading an OpenGL binding:
+
+```ruby
+require "texel/gl"
+
+Texel::GL.format(image)
+# => #<data Texel::GL::Format
+#      internal_format=:srgb8_alpha8 format=:rgba type=:unsigned_byte>
+```
+
+## Errors
+
+All library errors inherit from `Texel::Error`:
+
+- `Texel::DecodeError`
+- `Texel::EncodeError`
+- `Texel::FormatError`
+- `Texel::MissingCodecError`
+
+## Development
+
+Install development dependencies and run the complete suite:
+
+```sh
+bundle install
+bundle exec rake spec
+```
+
+`rake spec` builds the native extension first. The pure Ruby fallback can be
+checked independently:
+
+```sh
+TEXEL_DISABLE_NATIVE=1 bundle exec rspec
+```
+
+The committed minimal image corpus can be regenerated when ImageMagick is
+available:
+
+```sh
+bundle exec rake fixtures
+```
+
+The `Native gems` GitHub Actions workflow compiles and tests all supported Ruby
+and platform combinations. Tag builds collect the five platform gems and the
+source gem into a single workflow artifact for release.
+
+## License
+
+Texel is available under the MIT License. The vendored stb headers retain their
+upstream Public Domain/MIT dual-license notices.

data/Rakefile

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/clean"
+require "rspec/core/rake_task"
+require "rbconfig"
+
+EXTENSION_DIRECTORY = File.expand_path("ext/texel", __dir__)
+EXTENSION_FILE = File.join(EXTENSION_DIRECTORY, "texel_native.#{RbConfig::CONFIG.fetch("DLEXT")}")
+
+task :compile do
+  next if ENV["TEXEL_DISABLE_NATIVE"] == "1"
+
+  Dir.chdir(EXTENSION_DIRECTORY) do
+    sh RbConfig.ruby, "extconf.rb"
+    sh ENV.fetch("MAKE", "make")
+  end
+end
+
+RSpec::Core::RakeTask.new(:spec)
+task spec: :compile
+
+desc "Regenerate the minimal image codec fixtures"
+task fixtures: :compile do
+  sh RbConfig.ruby, File.expand_path("spec/fixtures/generate.rb", __dir__)
+end
+
+CLEAN.include(
+  File.join(EXTENSION_DIRECTORY, "Makefile"),
+  File.join(EXTENSION_DIRECTORY, "*.o"),
+  EXTENSION_FILE,
+  File.join(EXTENSION_DIRECTORY, "mkmf.log")
+)
+
+task default: :spec

data/ext/texel/extconf.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+if ENV["TEXEL_DISABLE_NATIVE"] == "1"
+  File.write(
+    "Makefile",
+    <<~MAKEFILE
+      .PHONY: all install clean
+      all:
+      install:
+      clean:
+    MAKEFILE
+  )
+  exit
+end
+
+require "mkmf"
+
+$CFLAGS = "#{$CFLAGS} -std=c99 -Wall -Wextra"
+$CFLAGS = "#{$CFLAGS} -Wno-unused-function -Wno-sign-compare"
+
+abort "texel requires a C99 compiler" unless try_compile(<<~C)
+  #include <stdint.h>
+  int main(void) { uint32_t value = 0; return (int)value; }
+C
+
+have_library("m", "sinf")
+
+create_makefile("texel/texel_native")

data/ext/texel/shim.c

@@ -0,0 +1,244 @@
+#include "shim.h"
+
+#include <math.h>
+#include <string.h>
+
+#define STBI_FAILURE_USERMSG
+#define STB_IMAGE_IMPLEMENTATION
+#define STB_IMAGE_WRITE_IMPLEMENTATION
+#define STB_IMAGE_RESIZE_IMPLEMENTATION
+#include "vendor/stb_image.h"
+#include "vendor/stb_image_write.h"
+#include "vendor/stb_image_resize2.h"
+
+unsigned char *
+tx_load_u8(const void *buffer, int length, int *width, int *height,
+           int *source_channels, int requested_channels, const char **error)
+{
+    unsigned char *pixels = stbi_load_from_memory(
+        (const stbi_uc *)buffer, length, width, height, source_channels, requested_channels);
+    if (pixels == NULL && error != NULL) {
+        *error = stbi_failure_reason();
+    }
+    return pixels;
+}
+
+unsigned short *
+tx_load_u16(const void *buffer, int length, int *width, int *height,
+            int *source_channels, int requested_channels, const char **error)
+{
+    unsigned short *pixels = stbi_load_16_from_memory(
+        (const stbi_uc *)buffer, length, width, height, source_channels, requested_channels);
+    if (pixels == NULL && error != NULL) {
+        *error = stbi_failure_reason();
+    }
+    return pixels;
+}
+
+float *
+tx_load_f32(const void *buffer, int length, int *width, int *height,
+            int *source_channels, int requested_channels, const char **error)
+{
+    float *pixels = stbi_loadf_from_memory(
+        (const stbi_uc *)buffer, length, width, height, source_channels, requested_channels);
+    if (pixels == NULL && error != NULL) {
+        *error = stbi_failure_reason();
+    }
+    return pixels;
+}
+
+int
+tx_info(const void *buffer, int length, int *width, int *height, int *channels)
+{
+    return stbi_info_from_memory((const stbi_uc *)buffer, length, width, height, channels);
+}
+
+int
+tx_is_16_bit(const void *buffer, int length)
+{
+    return stbi_is_16_bit_from_memory((const stbi_uc *)buffer, length);
+}
+
+int
+tx_is_hdr(const void *buffer, int length)
+{
+    return stbi_is_hdr_from_memory((const stbi_uc *)buffer, length);
+}
+
+void
+tx_free(void *pixels)
+{
+    stbi_image_free(pixels);
+}
+
+int
+tx_write(int format, tx_write_cb callback, void *user_data, int width, int height,
+         int channels, const void *pixels, int quality_or_stride)
+{
+    switch (format) {
+        case 0:
+            return stbi_write_png_to_func(callback, user_data, width, height, channels,
+                                          pixels, quality_or_stride);
+        case 1:
+            return stbi_write_jpg_to_func(callback, user_data, width, height, channels,
+                                          pixels, quality_or_stride);
+        case 2:
+            return stbi_write_bmp_to_func(callback, user_data, width, height, channels, pixels);
+        case 3:
+            return stbi_write_tga_to_func(callback, user_data, width, height, channels, pixels);
+        case 4:
+            return stbi_write_hdr_to_func(callback, user_data, width, height, channels,
+                                          (const float *)pixels);
+        default:
+            return 0;
+    }
+}
+
+static stbir_pixel_layout
+tx_pixel_layout(int channels, int premultiplied)
+{
+    switch (channels) {
+        case 1:
+            return STBIR_1CHANNEL;
+        case 2:
+            return premultiplied ? STBIR_RA_PM : STBIR_RA;
+        case 3:
+            return STBIR_RGB;
+        case 4:
+            return premultiplied ? STBIR_RGBA_PM : STBIR_RGBA;
+        default:
+            return STBIR_1CHANNEL;
+    }
+}
+
+static float
+tx_lanczos_kernel(float x, float scale, void *user_data)
+{
+    const float pi = 3.14159265358979323846f;
+    (void)scale;
+    (void)user_data;
+    if (x < 0.0f) {
+        x = -x;
+    }
+    if (x < 0.000001f) {
+        return 1.0f;
+    }
+    if (x >= 3.0f) {
+        return 0.0f;
+    }
+    return (sinf(pi * x) / (pi * x)) * (sinf((pi * x) / 3.0f) / ((pi * x) / 3.0f));
+}
+
+static float
+tx_lanczos_support(float scale, void *user_data)
+{
+    (void)scale;
+    (void)user_data;
+    return 3.0f;
+}
+
+int
+tx_resize(int dtype, int srgb, const void *source, int source_width, int source_height,
+          void *destination, int width, int height, int channels, int filter, int edge,
+          int premultiplied)
+{
+    stbir_datatype data_type;
+    if (dtype == 0) {
+        data_type = srgb ? STBIR_TYPE_UINT8_SRGB : STBIR_TYPE_UINT8;
+    } else if (dtype == 1) {
+        data_type = STBIR_TYPE_UINT16;
+    } else if (dtype == 2) {
+        data_type = STBIR_TYPE_FLOAT;
+    } else {
+        return 0;
+    }
+
+    if (filter == STBIR_FILTER_OTHER) {
+        STBIR_RESIZE resize;
+        stbir_resize_init(&resize, source, source_width, source_height, 0,
+                          destination, width, height, 0,
+                          tx_pixel_layout(channels, premultiplied), data_type);
+        if (!stbir_set_edgemodes(&resize, (stbir_edge)edge, (stbir_edge)edge) ||
+            !stbir_set_filter_callbacks(&resize,
+                                        tx_lanczos_kernel, tx_lanczos_support,
+                                        tx_lanczos_kernel, tx_lanczos_support)) {
+            return 0;
+        }
+        return stbir_resize_extended(&resize);
+    }
+
+    return stbir_resize(source, source_width, source_height, 0,
+                        destination, width, height, 0,
+                        tx_pixel_layout(channels, premultiplied), data_type,
+                        (stbir_edge)edge, (stbir_filter)filter) != NULL;
+}
+
+static uint16_t
+tx_float_to_half(float value)
+{
+    union {
+        float floating;
+        uint32_t bits;
+    } input;
+    uint32_t sign;
+    uint32_t exponent;
+    uint32_t mantissa;
+    int half_exponent;
+    uint32_t half_mantissa;
+    uint32_t remainder;
+    int shift;
+
+    input.floating = value;
+    sign = (input.bits >> 16) & 0x8000u;
+    exponent = (input.bits >> 23) & 0xffu;
+    mantissa = input.bits & 0x7fffffu;
+
+    if (exponent == 0xffu) {
+        return (uint16_t)(sign | (mantissa == 0 ? 0x7c00u : 0x7e00u));
+    }
+
+    half_exponent = (int)exponent - 127 + 15;
+    if (half_exponent >= 31) {
+        return (uint16_t)(sign | 0x7c00u);
+    }
+    if (half_exponent <= 0) {
+        if (half_exponent < -10) {
+            return (uint16_t)sign;
+        }
+        mantissa |= 0x800000u;
+        shift = 14 - half_exponent;
+        half_mantissa = mantissa >> shift;
+        remainder = mantissa & ((1u << shift) - 1u);
+        if (remainder > (1u << (shift - 1)) ||
+            (remainder == (1u << (shift - 1)) && (half_mantissa & 1u))) {
+            half_mantissa += 1u;
+        }
+        return (uint16_t)(sign | half_mantissa);
+    }
+
+    half_mantissa = mantissa >> 13;
+    remainder = mantissa & 0x1fffu;
+    if (remainder > 0x1000u || (remainder == 0x1000u && (half_mantissa & 1u))) {
+        half_mantissa += 1u;
+        if (half_mantissa == 0x400u) {
+            half_mantissa = 0;
+            half_exponent += 1;
+            if (half_exponent >= 31) {
+                return (uint16_t)(sign | 0x7c00u);
+            }
+        }
+    }
+    return (uint16_t)(sign | ((uint32_t)half_exponent << 10) | half_mantissa);
+}
+
+void
+tx_f32_to_f16(const void *source, uint16_t *destination, size_t count)
+{
+    const unsigned char *bytes = (const unsigned char *)source;
+    size_t index;
+    for (index = 0; index < count; index += 1) {
+        float value;
+        memcpy(&value, bytes + (index * sizeof(float)), sizeof(float));
+        destination[index] = tx_float_to_half(value);
+    }
+}

data/ext/texel/shim.h

@@ -0,0 +1,35 @@
+#ifndef TEXEL_SHIM_H
+#define TEXEL_SHIM_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void tx_write_cb(void *user_data, void *data, int size);
+
+unsigned char *tx_load_u8(const void *buffer, int length, int *width, int *height,
+                          int *source_channels, int requested_channels, const char **error);
+unsigned short *tx_load_u16(const void *buffer, int length, int *width, int *height,
+                            int *source_channels, int requested_channels, const char **error);
+float *tx_load_f32(const void *buffer, int length, int *width, int *height,
+                   int *source_channels, int requested_channels, const char **error);
+int tx_info(const void *buffer, int length, int *width, int *height, int *channels);
+int tx_is_16_bit(const void *buffer, int length);
+int tx_is_hdr(const void *buffer, int length);
+void tx_free(void *pixels);
+
+int tx_write(int format, tx_write_cb callback, void *user_data, int width, int height,
+             int channels, const void *pixels, int quality_or_stride);
+int tx_resize(int dtype, int srgb, const void *source, int source_width, int source_height,
+              void *destination, int width, int height, int channels, int filter, int edge,
+              int premultiplied);
+void tx_f32_to_f16(const void *source, uint16_t *destination, size_t count);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif