rb_sdl2 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 101f794f351d219f8cc70180a9f02cd57c11c507e8542fad5d83c2e4635ea7cd
-  data.tar.gz: fc7e00d5985c46af575e81cdbd2bfd177464f14eeb111e2dfae41cdaffb75e51
+  metadata.gz: 6e1202e5d4354c491782ad3d005ff73685498fe74db86b27fb5dd89e96bbd6e0
+  data.tar.gz: d3544770d711514d14ea918eaacf135569e8ccb0329ec52f956ea0fdfddde46a
 SHA512:
-  metadata.gz: 0dd39b4cb9da230fd7d63556a3db53be3d28eeee972a5a54aa945cffa246501d3684112d72b8f8b5f3f76cee58d47e21a226998ae791390c4f98d53222aa4cda
-  data.tar.gz: dca9330ed249b66a6b21ad6bc42a42a14cd014f95757529d3f9e14f927f0ca89c9989960e3403511ecb58d315ed28829ca8fa9a61e30a934250ee3cefc22d207
+  metadata.gz: f7675ac774fd74152857edbad3a319f5700336dbe7cc375f80b2775ddf9f4695a3a07ecfd5c667252252cb7907539efd28662cae29d9ae7424fa2776edf7cc8e
+  data.tar.gz: 8ec901e68e62c38d850c4ddeac7526e23bd433f3ad238327f60f4ab8529ad4c3a779301b231a82ad0bc20a39341c8c079b853fd1955be34eb397ef5f8114a137

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Deprecated
+
+### Fixed
+
+### Removed
+
+### Security
+
+## [0.1.1] - 2021-10-11
+
+### Added
+- Added metadata to gemspec.
+- Added document to Error, Platform, SDL, Surface, Timer, and Version.
+- Added description to README.md.
+
+### Changed
+- Changed the contents of Palette#inspect to something meaningful.
+
 ## [0.1.0] - 2021-10-10
 
 - Initial release

data/README.md

@@ -6,6 +6,20 @@ Ruby オブジェクトとして提供します。
 SDL 2.0.16 移行を対象としています。この Gem には SDL は含まれていません。
 利用する際は環境に合わせて SDL を用意してください。
 
+## Description
+
+RbSDL2 は SDL の機能やポインターを Ruby オブジェクトとして扱います。
+ポインター管理を RbSDL2 が行っているのでメモリー管理を気にせずに SDL の機能を使うことができます。
+最低限のマネージ機能も用意しています。例えばコールバック関数を設定した場合はそのオブジェクトを保持します。
+スコープを外れてもコアダンプすることはありません。
+
+[sdl2-bindings](https://rubygems.org/gems/sdl2-bindings) を基に構築していますので、
+オブジェクトの仕様や性能が気に入らない場合は直接（そして全ての） SDL 関数を呼び出すこともできます。
+各オブジェクトは外部からのポインターから作成することができます。
+C で書いたライブラリとの部分的な連携に利用することもできます。
+
+SDL の仕様や機能について知っている必要はありますが Ruby のコードを読めれば使えるようになっています。
+
 ## Installation
 
     $ gem install rb_sdl2

data/lib/rb_sdl2/error.rb

@@ -1,8 +1,12 @@
 module RbSDL2
   module Error
     class << self
+      # SDL が設定したエラーメッセージをクリアします。
       def clear = ::SDL2.SDL_ClearError
 
+      # SDL からのエラーメッセージを文字列で返します。
+      # SDL からエラーが通知されてもえらメッセージがあるとは限りません。
+      # SDL の関数はエラーの状態を示してもエラーメッセージをセットしない場合があります。
       def message = ::SDL2.SDL_GetError.read_string
     end
   end

data/lib/rb_sdl2/palette.rb

@@ -57,6 +57,10 @@ module RbSDL2
 
     def each = length.times { |nth| yield(self[nth]) }
 
+    def inspect
+      "#<#{self.class.name} ptr=#{to_ptr.inspect} colors=#{length} version=#{version}>"
+    end
+
     def length = @st[:ncolors]
 
     alias size length

data/lib/rb_sdl2/platform.rb

@@ -1,6 +1,8 @@
 module RbSDL2
   module Platform
     class << self
+      # プラットフォーム名（動作環境）を文字列で返します。
+      # ここでの動作環境は SDL ライブラリが認識しているものです。
       def platform = ::SDL2.SDL_GetPlatform.read_string
     end
   end

data/lib/rb_sdl2/sdl.rb

@@ -19,13 +19,25 @@ module RbSDL2
     end
 
     class << self
+      # SDL を初期化します。
+      # flags に起動したい SDL サブシステムをキーにオプション引数（値は true で起動）で与えます。
+      # flags を指定指定しない場合は全ての SDL コンポーネントが起動します。
+      # オプション引数のキーは audio, events, game_controller, haptic, joystick, sensor, timer, video
+      # があります。
       def init(**flags)
         err = ::SDL2.SDL_Init(InitFlags.to_num(**flags))
         raise RbSDL2Error if err < 0
       end
 
+      # SDL サブシステムが初期化されているか確認します。
+      # アプリケーション作成者が必要とする SDL サブシステム初期化されているか確認できます。
+      # flags に与えたオプションの状態と一致した時のみ true を返します。
+      # 部分的な一致の場合は false を返します。
       def init?(**flags) = ::SDL2.SDL_WasInit(mask = InitFlags.to_num(**flags)) == mask
 
+      # SDL を終了します。RbSDL2 ではアプリケーションの終了時にこのメソッドを呼ぶ必要はありません。
+      # 終了後に再び SDL サブシステムを起動する必要がある場合は再度 init メソッドを呼ぶことができます。
+      # このメソッドは何度でも呼び出すことができます。
       def quit = ::SDL2.SDL_Quit
     end
   end

data/lib/rb_sdl2/surface.rb

@@ -30,8 +30,13 @@ module RbSDL2
     require_relative 'pixel_format_enum'
 
     class << self
-      # 変換ができない場合はエラーを発生させる。
-      # 変換先がインデックスカラー（INDEX8）の時は期待する変換は行われない。
+      # 指定した Surface オブジェクトを基に指定した画像フォーマットの新しい Surface オブジェクトを柵瀬します。
+      # surface へ変換元の Surface オブジェクトを与えます。
+      # new_format へ変換先の画像フォーマット(PixelFormatEnumの名前か番号)を与えます。
+      # 変換ができない場合は例外（RbSDL2::RbSDL2Error）を発生させます。
+      # INDEX1*, INDEX4*, ARGB2101010、FOURCC系への変換はできません。
+      # 変換先がインデックスカラー（INDEX8）の時は例外は発生しませんが期待する変換は行われません。
+      # その時はサーフェィス全面がインデックス番号０で埋められています。
       def convert(surface, new_format)
         ptr = SurfacePointer.new(
           ::SDL2.SDL_ConvertSurfaceFormat(surface, PixelFormatEnum.to_num(new_format), 0))
@@ -43,9 +48,17 @@ module RbSDL2
 
       require_relative 'rw_ops'
 
+      # ファイルから画像を読み込み新たな Surface オブジェクトを生成します。
+      # file へ読み込む画像ファイルのパスを与えます。
+      # 対応する画像は BMP 形式のみです。
+      # 読み込みができない場合は例外（RbSDL2::RbSDL2Error）を発生させます。
+      # インデックスカラー（2色、16色）は INDEX8 フォーマットとして読み込まれます。
       def load(file) = RWOps.new(file, "rb") { |rw| load_rw(rw) }
 
-      # load_rw は与えられたオブジェクトをオートクローズしません。
+      # RWOps から画像を読み込み新たな Surface オブジェクトを生成します。
+      # rw へ RbSDL2::RWOps オブジェクトか SDL_RWOps ポインターを与えます。
+      # 読み込みができない場合は例外（RbSDL2::RbSDL2Error）を発生させます。
+      # このメソッドは与えられたオブジェクトをクローズしません。
       def load_rw(rw)
         ptr = SurfacePointer.new(::SDL2.SDL_LoadBMP_RW(rw, 0))
         raise RbSDL2Error if ptr.null?
@@ -54,6 +67,10 @@ module RbSDL2
         obj
       end
 
+      # 新しい Surface オブジェクトを生成します。
+      # w へ画像の幅ピクセル数
+      # h へ画像の縦ピクセル数
+      # format へ画像フォーマット(PixelFormatEnumの名前か番号)を与えます。
       def new(w, h, format)
         ptr = SurfacePointer.new(
           ::SDL2.SDL_CreateRGBSurfaceWithFormat(0, w, h, 0, PixelFormatEnum.to_num(format)))
@@ -61,6 +78,10 @@ module RbSDL2
         super(ptr)
       end
 
+      # ポインターから Surface オブジェクトを生成します。
+      # ptr へ対象となるポインターを与えます。
+      # このメソッドは SDL_Surface 構造体の参照カウンターをサポートしています。
+      # 生成した Surface オブジェクトは SDL 側で破棄しても Ruby 側のスコープに存在していれば安全に使用できます。
       def to_ptr(ptr)
         obj = allocate
         obj.__send__(:initialize, SurfacePointer.to_ptr(ptr))

data/lib/rb_sdl2/timer.rb

@@ -1,21 +1,30 @@
 module RbSDL2
   module Timer
     class << self
+      # ms へ与えたミリ秒だけスレッドを停止します。SDL のタイマーを使用しています。
+      # ms が負の数だった場合 ArgumentError が発生します。
       def delay(ms)
         raise ArgumentError if ms < 0
         ::SDL2.SDL_Delay(ms)
       end
 
+      # performance_count の 1 秒あたりの増加量を返します。
       def performance_frequency = ::SDL2.SDL_GetPerformanceFrequency
 
+      # SDL が提供する高精度カウンターの値を返します。
+      # 返ってくる値には意味がありません。精度も SDL の実装や動作環境ごとに違います。
       def performance_count = ::SDL2.SDL_GetPerformanceCounter
 
+      # 与えられたブロックの実行時間を返します。単位は秒です。
+      # 実行時間の計測に SDL の高精度カウンターを使用しています。
       def realtime
         t = performance_count
         yield
         (performance_count - t).fdiv(performance_frequency)
       end
 
+      # SDL が起動してからの経過時間をミリ秒で返します。
+      # SDL のタイマーを使用しており、49日ほどで 0 に戻ります。
       def ticks = ::SDL2.SDL_GetTicks
     end
   end

data/lib/rb_sdl2/version.rb

@@ -1,8 +1,10 @@
 module RbSDL2
   module Version
     class << self
+      # SDL ライブラリのリビジョンを文字列で返します。
       def revision = ::SDL2.SDL_GetRevision.read_string
 
+      # SDL ライブラリのバージョン番号を文字列で返します。形式はセマンティックバージョニングです。
       def version
         st = ::SDL2::SDL_version.new
         ::SDL2.SDL_GetVersion(st)

data/rb_sdl2.gemspec

@@ -2,14 +2,22 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "rb_sdl2"
-  spec.version       = "0.1.0"
+  spec.version       = "0.1.1"
   spec.author        = "shinokaro"
   spec.email         = "shinokaro@hotmail.co.jp"
+
   spec.summary       = "Multimedia library with SDL."
   spec.description   = "RbSDL2 treats the functions and pointers provided by SDL as Ruby objects."
+  spec.homepage      = "https://github.com/shinokaro/rb_sdl2/blob/main/README.md"
   spec.license       = "Zlib"
   spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
 
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/shinokaro/rb_sdl2/issues'
+  spec.metadata["changelog_uri"] = "https://github.com/shinokaro/rb_sdl2/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/rb_sdl2"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/shinokaro/rb_sdl2"
+
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rb_sdl2
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - shinokaro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-10 00:00:00.000000000 Z
+date: 2021-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -109,10 +109,15 @@ files:
 - lib/rb_sdl2/window/size.rb
 - lib/rb_sdl2/window/window_flags.rb
 - rb_sdl2.gemspec
-homepage:
+homepage: https://github.com/shinokaro/rb_sdl2/blob/main/README.md
 licenses:
 - Zlib
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/shinokaro/rb_sdl2/issues
+  changelog_uri: https://github.com/shinokaro/rb_sdl2/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/rb_sdl2
+  homepage_uri: https://github.com/shinokaro/rb_sdl2/blob/main/README.md
+  source_code_uri: https://github.com/shinokaro/rb_sdl2
 post_install_message:
 rdoc_options: []
 require_paths: