rays-video 0.1.2

data/README.md

@@ -0,0 +1,147 @@
+# Rays Video - Video support for Rays
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xord/rays-video)
+![License](https://img.shields.io/github/license/xord/rays-video)
+![Build Status](https://github.com/xord/rays-video/actions/workflows/test.yml/badge.svg)
+![Gem Version](https://badge.fury.io/rb/rays-video.svg)
+
+## ⚠️  Notice
+
+This repository is a read-only mirror of our monorepo.
+We do not accept pull requests or direct contributions here.
+
+### 🔄 Where to Contribute?
+
+All development happens in our [xord/all](https://github.com/xord/all) monorepo, which contains all our main libraries.
+If you'd like to contribute, please submit your changes there.
+
+For more details, check out our [Contribution Guidelines](./CONTRIBUTING.md).
+
+Thanks for your support! 🙌
+
+## 🚀 About
+
+**Rays Video** is a small extension to [Rays](https://github.com/xord/rays) that adds video reading, writing, and frame-level manipulation. A `Rays::Video` is, conceptually, an ordered list of `Rays::Image` frames with a frame rate and a pixel density — you can build one from scratch, append / insert / remove frames, scrub a playback position, load a video from disk, save it back out, or grab any frame as a regular `Rays::Image` to draw with.
+
+Audio support is built on [Beeps](https://github.com/xord/beeps) — video files keep their audio track and it can be fed into a Beeps processor chain.
+
+Like the rest of the `xord/*` family, this gem is primarily developed for our own use, but it works as a standalone video gem.
+
+> **Platform status:** macOS / iOS only at the moment. Windows and Linux backends are not yet implemented.
+
+## 📋 Requirements
+
+- Ruby **3.0.0** or later
+- A C++ compiler with C++20 support
+- [Xot](https://rubygems.org/gems/xot), [Rucy](https://rubygems.org/gems/rucy), [Beeps](https://rubygems.org/gems/beeps), and [Rays](https://rubygems.org/gems/rays) (declared as runtime dependencies)
+- **macOS / iOS** — AVFoundation (bundled with the OS)
+
+## 📦 Installation
+
+Add this line to your Gemfile:
+```ruby
+gem 'rays-video'
+```
+
+Then install:
+```bash
+$ bundle install
+```
+
+Or install it directly:
+```bash
+$ gem install rays-video
+```
+
+## 📚 What's Provided
+
+### `Rays::Video`
+
+A finite sequence of `Rays::Image` frames with a fixed `width`, `height`, `fps`, and `pixel_density`.
+
+| Method                                     | Purpose                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| `Video.new(width, height, fps:, pixel_density:)` | Create an empty video (`fps` defaults to 30)                 |
+| `Video.load(path)`                         | Load a video file from disk                                        |
+| `Video.exts`                               | Supported video file extensions on the current platform            |
+| `video.append(*images)`                    | Append one or more frames                                          |
+| `video.insert(index, *images)`             | Insert frames at the given index                                   |
+| `video.remove(index)`                      | Remove the frame at the given index                                |
+| `video.each { \|image\| ... }`             | Iterate frames (also includes `Enumerable`)                        |
+| `video[i]`                                 | Get the frame at index *i* as a `Rays::Image`                      |
+| `video.pos` / `video.pos =`                | Current playback position (index)                                  |
+| `video.play` / `video.pause` / `video.stop`| Playback controls                                                  |
+| `video.time_scale` / `video.time_scale =`  | Speed multiplier for playback                                      |
+| `video.size`, `video.empty?`               | Frame count / emptiness                                            |
+| `video.width`, `video.height`, `video.fps`, `video.pixel_density` | Read-only metadata                          |
+| `video.dup`                                | Deep-ish copy (shares image references)                            |
+| `video.save(path)`                         | Encode the video to a file                                         |
+| `video.to_image` (`Image()` cast)          | Get the frame at the current `pos` as a `Rays::Image`              |
+
+## 💡 Usage
+
+### Build a video from frames and save it
+
+```ruby
+require 'rays'
+require 'rays/video'
+
+video = Rays::Video.new(320, 240, fps: 30)
+
+60.times do |n|
+  frame = Rays::Image.new(320, 240)
+  frame.paint do |p|
+    p.background 0
+    p.fill 1, 0.5, 0.1
+    p.ellipse n * 5, 120, 60, 60
+  end
+  video.append frame
+end
+
+video.save 'out.mp4'
+```
+
+### Load a video and draw a frame
+
+```ruby
+require 'rays'
+require 'rays/video'
+
+video = Rays::Video.load 'clip.mp4'
+puts "#{video.width}×#{video.height} @ #{video.fps}fps, #{video.size} frames"
+
+# get the 30th frame as an Image and save it
+video[30].save 'frame30.png'
+```
+
+### Scrub through a video
+
+```ruby
+video = Rays::Video.load 'clip.mp4'
+
+video.pos = 0
+target = Rays::Image.new video.width, video.height
+target.paint do |p|
+  p.image video.to_image
+end
+
+video.pos = video.size / 2     # mid-point
+mid = video.to_image
+```
+
+## 🛠️ Development
+
+```bash
+$ rake lib    # build the native C++ library (librays-video)
+$ rake ext    # build the Ruby C extension
+$ rake test   # run the test suite (macOS / iOS only)
+$ rake doc    # generate RDoc from C++ sources
+$ rake       # default: builds the extension
+```
+
+In the [`xord/all`](https://github.com/xord/all) monorepo you can scope by module, e.g. `rake rays-video test`.
+
+## 📜 License
+
+**Rays Video** is licensed under the MIT License.
+See the [LICENSE](./LICENSE) file for details.

data/Rakefile

@@ -0,0 +1,25 @@
+# -*- mode: ruby -*-
+
+%w[../xot ../rucy ../beeps ../rays .]
+  .map  {|s| File.expand_path "#{s}/lib", __dir__}
+  .each {|s| $:.unshift s if !$:.include?(s) && File.directory?(s)}
+
+require 'rucy/rake'
+
+require 'xot/extension'
+require 'rucy/extension'
+require 'beeps/extension'
+require 'rays/extension'
+require 'rays-video/extension'
+
+
+EXTENSIONS  = [Xot, Rucy, Beeps, Rays, RaysVideo]
+TESTS_ALONE = []
+
+default_tasks :ext
+use_bundler
+build_native_library
+build_ruby_extension
+test_ruby_extension unless github_actions? && win32?
+generate_documents
+build_ruby_gem

data/VERSION

@@ -0,0 +1 @@
+0.1.2

data/ext/rays-video/defs.h

@@ -0,0 +1,17 @@
+// -*- c++ -*-
+#pragma once
+#ifndef __RAYS_VIDEO_EXT_DEFS_H__
+#define __RAYS_VIDEO_EXT_DEFS_H__
+
+
+#include <rucy.h>
+#include "rays/defs.h"
+#include "rays/ruby/defs.h"
+
+
+using namespace Rucy;
+
+using Rays::coord;
+
+
+#endif//EOH

data/ext/rays-video/extconf.rb

@@ -0,0 +1,23 @@
+%w[../xot ../rucy ../beeps ../rays .]
+  .map  {|s| File.expand_path "../../#{s}/lib", __dir__}
+  .each {|s| $:.unshift s if !$:.include?(s) && File.directory?(s)}
+
+require 'mkmf'
+require 'xot/extconf'
+require 'xot/extension'
+require 'rucy/extension'
+require 'beeps/extension'
+require 'rays/extension'
+require 'rays-video/extension'
+
+
+Xot::ExtConf.new Xot, Rucy, Beeps, Rays, RaysVideo do
+  setup do
+    headers    << 'ruby.h'
+    libs.unshift 'gdi32', 'opengl32', 'glew32'            if win32?
+    frameworks << 'AppKit' << 'AVFoundation'              if osx?
+    $LDFLAGS   << ' -Wl,--out-implib=librays-video.dll.a' if mingw? || cygwin?
+  end
+
+  create_makefile 'rays_video_ext'
+end

data/ext/rays-video/native.cpp

@@ -0,0 +1,17 @@
+#include "defs.h"
+
+
+void Init_rays_video ();
+
+
+extern "C" void
+Init_rays_video_ext ()
+{
+	RUCY_TRY
+
+	Rucy::init();
+
+	Init_rays_video();
+
+	RUCY_CATCH
+}

data/ext/rays-video/video.cpp

@@ -0,0 +1,282 @@
+#include "rays-video/ruby/video.h"
+
+
+#include "rays/ruby/image.h"
+#include "defs.h"
+
+
+RUCY_DEFINE_VALUE_FROM_TO(RAYS_VIDEO_EXPORT, Rays::Video)
+
+#define THIS  to<Rays::Video*>(self)
+
+#define CHECK RUCY_CHECK_OBJECT(Rays::Video, self)
+
+
+static
+RUCY_DEF_ALLOC(alloc, klass)
+{
+	return new_type<Rays::Video>(klass);
+}
+RUCY_END
+
+static
+RUCY_DEF4(initialize, width, height, fps, pixel_density)
+{
+	RUCY_CHECK_OBJ(Rays::Video, self);
+
+	float fps_ = to<float>(fps);
+	*THIS = Rays::Video(
+		to<int>(width),
+		to<int>(height),
+		fps_ > 0 ? fps_ : (float) Rays::Video::DEFAULT_FPS,
+		to<float>(pixel_density));
+}
+RUCY_END
+
+static
+RUCY_DEF1(initialize_copy, obj)
+{
+	RUCY_CHECK_OBJ(Rays::Video, self);
+
+	*THIS = to<Rays::Video&>(obj).dup();
+}
+RUCY_END
+
+static
+RUCY_DEF2(insert, index, image)
+{
+	CHECK;
+	THIS->insert(to<size_t>(index), to<const Rays::Image&>(image));
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF1(append, image)
+{
+	CHECK;
+	THIS->append(to<const Rays::Image&>(image));
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF1(remove, index)
+{
+	CHECK;
+	THIS->remove(to<size_t>(index));
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF1(save, path)
+{
+	CHECK;
+	THIS->save(path.c_str());
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF0(width)
+{
+	CHECK;
+	return value(THIS->width());
+}
+RUCY_END
+
+static
+RUCY_DEF0(height)
+{
+	CHECK;
+	return value(THIS->height());
+}
+RUCY_END
+
+static
+RUCY_DEF0(fps)
+{
+	CHECK;
+	return value(THIS->fps());
+}
+RUCY_END
+
+static
+RUCY_DEF0(pixel_density)
+{
+	CHECK;
+	return value(THIS->pixel_density());
+}
+RUCY_END
+
+static
+RUCY_DEF0(size)
+{
+	CHECK;
+	return value(THIS->size());
+}
+RUCY_END
+
+static
+RUCY_DEF0(empty)
+{
+	CHECK;
+	return value(THIS->empty());
+}
+RUCY_END
+
+static
+RUCY_DEF1(set_position, position)
+{
+	CHECK;
+	THIS->set_position(to<size_t>(position));
+	return position;
+}
+RUCY_END
+
+static
+RUCY_DEF0(get_position)
+{
+	CHECK;
+	return value(THIS->position());
+}
+RUCY_END
+
+static
+RUCY_DEF0(each)
+{
+	CHECK;
+	Value ret;
+	for (auto it = THIS->begin(), end = THIS->end(); it != end; ++it)
+		ret = rb_yield(value(*it));
+	return ret;
+}
+RUCY_END
+
+static
+RUCY_DEF0(to_image)
+{
+	CHECK;
+	return value((Rays::Image) *THIS);
+}
+RUCY_END
+
+static
+RUCY_DEF1(at, index)
+{
+	CHECK;
+	return value((*THIS)[(size_t) to<int>(index)]);
+}
+RUCY_END
+
+static
+RUCY_DEF0(play)
+{
+	CHECK;
+	THIS->play();
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF0(pause)
+{
+	CHECK;
+	THIS->pause();
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF0(stop)
+{
+	CHECK;
+	THIS->stop();
+	return self;
+}
+RUCY_END
+
+static
+RUCY_DEF1(set_time_scale, scale)
+{
+	CHECK;
+	THIS->set_time_scale(to<float>(scale));
+	return scale;
+}
+RUCY_END
+
+static
+RUCY_DEF0(get_time_scale)
+{
+	CHECK;
+	return value(THIS->time_scale());
+}
+RUCY_END
+
+static
+RUCY_DEF1(load, path)
+{
+	return value(Rays::load_video(path.c_str()));
+}
+RUCY_END
+
+static
+RUCY_DEF0(exts)
+{
+	std::vector<Value> list;
+	for (const auto& ext : Rays::get_video_exts())
+		list.emplace_back(ext.c_str());
+	return array(list.data(), list.size());
+}
+RUCY_END
+
+
+static Class cVideo;
+
+void
+Init_rays_video ()
+{
+	Module mRays = define_module("Rays");
+
+	cVideo = mRays.define_class("Video");
+	cVideo.define_alloc_func(alloc);
+	cVideo.define_private_method("initialize!",     initialize);
+	cVideo.define_private_method("initialize_copy", initialize_copy);
+	cVideo.define_method("insert!", insert);
+	cVideo.define_method("append!", append);
+	cVideo.define_method("remove!", remove);
+	cVideo.define_method("save", save);
+	cVideo.define_method("width",         width);
+	cVideo.define_method("height",        height);
+	cVideo.define_method("fps",           fps);
+	cVideo.define_method("pixel_density", pixel_density);
+	cVideo.define_method("size",          size);
+	cVideo.define_method("empty?",        empty);
+	cVideo.define_method("position=", set_position);
+	cVideo.define_method("position",  get_position);
+	cVideo.define_method("play",  play);
+	cVideo.define_method("pause", pause);
+	cVideo.define_method("stop",  stop);
+	cVideo.define_method("time_scale=", set_time_scale);
+	cVideo.define_method("time_scale",  get_time_scale);
+	cVideo.define_method("each!", each);
+	cVideo.define_method("to_image", to_image);
+	cVideo.define_method("[]", at);
+	cVideo.define_module_function("load", load);
+	cVideo.define_module_function("exts", exts);
+}
+
+
+namespace Rays
+{
+
+
+	Class
+	video_class ()
+	{
+		return cVideo;
+	}
+
+
+}// Rays

data/include/rays/video.h

@@ -0,0 +1,102 @@
+// -*- c++ -*-
+#pragma once
+#ifndef __RAYS_VIDEO_H__
+#define __RAYS_VIDEO_H__
+
+
+#include <vector>
+#include <xot/pimpl.h>
+#include <xot/string.h>
+#include <rays/defs.h>
+#include <rays/image.h>
+
+
+namespace Rays
+{
+
+
+	class Video
+	{
+
+		typedef Video This;
+
+		public:
+
+			typedef std::vector<Image> ImageList;
+
+			typedef ImageList::const_iterator const_iterator;
+
+			enum {DEFAULT_FPS = 30};
+
+			Video ();
+
+			Video (
+				int width, int height,
+				float fps = DEFAULT_FPS, float pixel_density = 1);
+
+			~Video ();
+
+			This dup () const;
+
+			void insert (size_t index, const Image& image);
+
+			void append (const Image& image);
+
+			void remove (size_t index);
+
+			void play ();
+
+			void pause ();
+
+			void stop ();
+
+			void set_time_scale (float scale);
+
+			float    time_scale () const;
+
+			void save (const char* path);
+
+			coord width () const;
+
+			coord height () const;
+
+			float fps () const;
+
+			float pixel_density () const;
+
+			size_t size () const;
+
+			bool empty () const;
+
+			void set_position (size_t index);
+
+			size_t   position () const;
+
+			const_iterator begin () const;
+
+			const_iterator end () const;
+
+			Image operator [] (size_t index) const;
+
+			operator Image () const;
+
+			operator bool () const;
+
+			bool operator ! () const;
+
+			struct Data;
+
+			Xot::PSharedImpl<Data> self;
+
+	};// Video
+
+
+	Video load_video (const char* path);
+
+	const StringList& get_video_exts ();
+
+
+}// Rays
+
+
+#endif//EOH

data/include/rays-video/ruby/video.h

@@ -0,0 +1,47 @@
+// -*- c++ -*-
+#pragma once
+#ifndef __RAYS_VIDEO_RUBY_VIDEO_H__
+#define __RAYS_VIDEO_RUBY_VIDEO_H__
+
+
+#include <rucy/class.h>
+#include <rucy/extension.h>
+#include <rays/video.h>
+
+
+#if defined(WIN32) && defined(GCC) && defined(RAYS_VIDEO)
+	#define RAYS_VIDEO_EXPORT __declspec(dllexport)
+#else
+	#define RAYS_VIDEO_EXPORT
+#endif
+
+
+RUCY_DECLARE_VALUE_FROM_TO(RAYS_VIDEO_EXPORT, Rays::Video)
+
+
+namespace Rays
+{
+
+
+	RAYS_VIDEO_EXPORT Rucy::Class video_class ();
+	// class Rays::Video
+
+
+}// Rays
+
+
+namespace Rucy
+{
+
+
+	template <> inline Class
+	get_ruby_class<Rays::Video> ()
+	{
+		return Rays::video_class();
+	}
+
+
+}// Rucy
+
+
+#endif//EOH

data/include/rays-video/ruby.h

@@ -0,0 +1,10 @@
+// -*- c++ -*-
+#pragma once
+#ifndef __RAYS_VIDEO_RUBY_ALL_H__
+#define __RAYS_VIDEO_RUBY_ALL_H__
+
+
+#include <rays-video/ruby/video.h>
+
+
+#endif//EOH

data/include/rays-video.h

@@ -0,0 +1,10 @@
+// -*- c++ -*-
+#pragma once
+#ifndef __RAYS_VIDEO_ALL_H__
+#define __RAYS_VIDEO_ALL_H__
+
+
+#include <rays/video.h>
+
+
+#endif//EOH