opengl-registry 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 140b56969d6bf604555783463786f8c26cf5df295867117030082ea8ea554569
+  data.tar.gz: 0e4416074336ef92dca0946b188fb2afbfa19b40046aa054a73f47bfda269a11
+SHA512:
+  metadata.gz: 50fa00baa919c7556ce6b4628be3d5c3ec0a0938770c083519939276d247925ddc5e0b0f6c1802b6b72e373b84bab0bd3c20c0ed2e9b44ae6da5d87b61949efc
+  data.tar.gz: 7415697ad77a33c8148d9a1fb97fe97a59e79f154e3704b84593a7fa4fe9faac0894d2237c8ee236b915e8ff99ad2639796b2a29d9ca40a567c1c0c68ffdb206

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.1
+before_install: gem install bundler -v 2.1.4

data/.yardopts

@@ -0,0 +1,7 @@
+--readme README.md
+--title 'OpenGL Registry'
+--charset utf-8
+--markup markdown
+--protected
+lib/**/*.rb
+--exclude lib/opengl/registry/words.rb

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Version History
+
+## 1.0
+* Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 ForeverZer0
+
+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,85 @@
+# OpenGL Registry
+
+Parses the Khronos OpenGL registry into a standardized and user-friendly data structure that can be walked through, providing an essential need for tools that generate code to create an OpenGL wrapper/bindings, for any language. Given an API name, version, and profile, is capable of filtering and grouping data structures that cover that specific subset of definitions, using a typical Ruby object-oriented approach.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'opengl-registry'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install opengl-registry
+
+## Usage
+
+#### Get the OpenGL Registry from Khronos
+
+You can either download the latest copy of [gl.xml](https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/gl.xml) directly from the [Khronos repo](https://github.com/KhronosGroup/OpenGL-Registry/tree/master/), or fetch it through the API.
+
+```ruby
+require 'opengl-registry'
+
+GL::Registry.download('/path/to/save/gl.xml')
+```
+
+For successive runs, you can simply check that the version you have is up to date.
+```ruby
+if GL::Registry.outdated?('/path/to/gl.xml')
+  # Download updated copy
+end
+```
+
+#### Create a Registry instance
+
+First step is to create the registry, which is essentially a container that stores every definition defined for OpenGL, OpenGLES (Embedded Systems), and OpenGLSC (Security Critical).
+
+```ruby
+registry = GL::Registry.load('/path/to/gl.xml')
+```
+
+Alternatively, if you have the XML as a string...
+```ruby
+registry = GL::Registry.parse(xml_string)
+```
+
+#### Create the OpenGL specification you wish to target
+
+In order to filter results and definitions by a subset of the API, version, profile, etc, create a new spec.
+
+```ruby
+extensions = ['GL_ARB_get_program_binary', 'GL_ARB_texture_storage']
+spec = GL::Spec.new(registry, :gl, 3.3, :core, extensions)
+```
+
+The created `spec` object can be then used to enumerate through every definition that this subset defines. The data will automatically be filtered and sorted, allowing for easy inspection of each entity.
+
+```ruby
+spec.functions.each do |function|
+  # Print out the function name and return type
+  puts "#{function.name} (#{function.type})"
+    
+  # Loop through argument definitions
+  function.arguments.each do |argument|
+    puts "  #{argument.name} (#{argument.type})"
+  end
+end
+
+spec.enums.each do |enum|
+  # Enums also define "groups" for creating C-style enumeration types, etc
+  puts "#{enum.name} = #{enum.value}"
+end
+```
+
+There are many helper functions throughout for detailed filtering, and retrieving any relevant information that might be required, such as generating bindings for a particular language, etc. See the [documentation](https://www.rubydoc.info/gems/opengl-registry/1.0.0) for more details.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "opengl/registry"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/opengl/registry.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require 'ox'
+require 'net/http'
+require 'json'
+require 'open-uri'
+require 'fileutils'
+
+require_relative 'registry/version'
+require_relative 'registry/words'
+require_relative 'registry/token'
+require_relative 'registry/native_type'
+require_relative 'registry/group'
+require_relative 'registry/enum'
+require_relative 'registry/argument'
+require_relative 'registry/function'
+require_relative 'registry/feature_provider'
+require_relative 'registry/feature'
+require_relative 'registry/feature_group'
+require_relative 'registry/extension'
+require_relative 'spec'
+
+##
+# Top-level namespace.
+#
+# @author Eric "ForeverZer0" Freed
+module GL
+
+  ##
+  # Container for all definitions of the OpenGL registry.
+  #
+  # @example
+  #
+  #   # Check if registry XML file is up to data
+  #   if GL::Registry.outdated?('gl.xml')
+  #     GL::Registry.download('gl.xml')
+  #   end
+  #
+  #   registry = GL::Registry.load('gl.xml')
+  #   spec = GL::Spec.new(registry, :gl, 3.3, :core)
+  #
+  #   # Use "spec" object to enumerate over detailed objects defining each token
+  #
+  class Registry
+
+    ##
+    # An array of OpenGL type names, as symbols.
+    GL_TYPES = %i[
+      GLenum GLboolean GLbitfield GLvoid GLbyte GLubyte GLshort GLushort GLint
+      GLuint GLclampx GLsizei GLfloat GLclampf GLdouble GLclampd
+      GLeglClientBufferEXT GLeglImageOES GLchar GLhandleARB GLhalf GLhalfARB
+      GLfixed GLintptr GLintptrARB GLsizeiptr GLsizeiptrARB GLint64 GLint64EXT
+      GLuint64 GLuint64EXT GLsync struct\ _cl_context struct\ _cl_event
+      GLDEBUGPROC GLDEBUGPROCARB GLDEBUGPROCKHR GLDEBUGPROCAMD GLhalfNV
+      GLvdpauSurfaceNV GLVULKANPROCNV
+    ].freeze
+    
+    ##
+    # @return [Array<Group>] a collection of all enumeration groups defined by OpenGL.
+    # @note This is for reference only, and should not be used for building definitions or determining a comprehensive
+    #   list of which enum values belong in each group, use the {Enum#groups} property instead.
+    attr_reader :groups
+
+    ##
+    # @return [Array<Function>] a complete collection of all OpenGL functions.
+    attr_reader :functions
+
+    ##
+    # @!attribute [r] enums
+    #   @return [Array<Enum>] a complete collection of all OpenGL enum values.
+
+    ##
+    # @return [Array<FeatureGroup>] a complete collection of all OpenGL feature groups.
+    attr_reader :features
+
+    ##
+    # @return [Array<Extension>] a complete collection of all OpenGL extensions.
+    attr_reader :extensions
+
+    ##
+    # Creates a new {Registry} from the specified XML file.
+    #
+    # @param path [String] The path to the registry file.
+    #
+    # @return [Registry] a newly created and parsed {Registry}.
+    def self.load(path)
+      doc = Ox.load_file(path, mode: :generic)
+      new(doc.root)
+    end
+
+    ##
+    # Creates a new {Registry} from the specified XML string.
+    #
+    # @param xml [String] The OpenGL registry as an XML string.
+    #
+    # @return [Registry] a newly created and parsed {Registry}.
+    def self.parse(xml)
+      doc = Ox.load(xml, mode: :generic)
+      new(doc.root)
+    end
+
+    ##
+    # @return [Array<Symbol>] an array of Symbol objects that represent each defined API in the registry.
+    def api_names
+      # RubyMine warns that the return value is wrong. It lies.
+      #noinspection RubyYardReturnMatch
+      @features.map(&:api).uniq
+    end
+
+    ##
+    # Retrieves an array of profiles defined in the registry.
+    #
+    # @overload profiles
+    #
+    # @overload profiles(api)
+    #   @param api [Symbol] An API to limit results to a specific API.
+    #
+    # @overload profiles(api, version)
+    #   @param api [Symbol] An API to limit results to a specific API.
+    #   @param version [String|Float] A version to limit results to.
+    #
+    # @return [Array<Symbol>] an array of defined profiles.
+    def profiles(api = nil, version = '1.0')
+      # RubyMine warns that the return value is wrong. It lies.
+      if api
+        values = @features.find_all { |group| group.api == api && group.version <= version.to_s }
+        #noinspection RubyYardReturnMatch
+        return values.flat_map(&:additions).map(&:profile).uniq
+      end
+      #noinspection RubyYardReturnMatch
+      @features.flat_map(&:additions).map(&:profile).uniq
+    end
+
+    def enums
+      #noinspection RubyResolve
+      @enums ||= each_enum.to_a
+    end
+
+    ##
+    # Enumerates through each enum defined in the registry.
+    #
+    # @overload each_enum
+    #   When called without a block, returns an Enumerator.
+    #   @return [Enumerator] An enum enumerator.
+    #
+    # @overload each_enum(&block)
+    #   When called with a block, yields each item to the block and returns `nil`.
+    #   @yieldparam enum [Enum] Yields an enum to the block.
+    #   @return [void]
+    def each_enum
+      #noinspection RubyYardReturnMatch
+      return enum_for(__method__) unless block_given?
+      @groups.each do |group|
+        group.members.each { |item| yield item }
+      end
+      nil
+    end
+
+    ##
+    # Enumerates through each group defined in the registry.
+    #
+    # @overload each_group
+    #   When called without a block, returns an Enumerator.
+    #   @return [Enumerator] A group enumerator.
+    #
+    # @overload each_group(&block)
+    #   When called with a block, yields each item to the block and returns `nil`.
+    #   @yieldparam group [Group] Yields a group to the block.
+    #   @return [void]
+    def each_group
+      #noinspection RubyYardReturnMatch
+      return enum_for(__method__) unless block_given?
+      @groups.each { |item| yield item }
+      nil
+    end
+
+    ##
+    # Enumerates through each function defined in the registry.
+    #
+    # @overload each_function
+    #   When called without a block, returns an Enumerator.
+    #   @return [Enumerator] A function enumerator.
+    #
+    # @overload each_function(&block)
+    #   When called with a block, yields each item to the block and returns `nil`.
+    #   @yieldparam enum [Function] Yields a function to the block.
+    #   @return [void]
+    def each_function
+      #noinspection RubyYardReturnMatch
+      return enum_for(__method__) unless block_given?
+      @functions.each { |item| yield item }
+      nil
+    end
+
+    ##
+    # Enumerates through each feature group defined in the registry.
+    #
+    # @overload each_feature
+    #   When called without a block, returns an Enumerator.
+    #   @return [Enumerator] A feature group enumerator.
+    #
+    # @overload each_feature(&block)
+    #   When called with a block, yields each item to the block and returns `nil`.
+    #   @yieldparam enum [FeatureGroup] Yields a group to the block.
+    #   @return [void]
+    def each_feature
+      #noinspection RubyYardReturnMatch
+      return enum_for(__method__) unless block_given?
+      @features.each { |item| yield item }
+      nil
+    end
+
+    ##
+    # Enumerates through each extension defined in the registry.
+    #
+    # @overload each_enum
+    #   When called without a block, returns an Enumerator.
+    #   @return [Enumerator] An extension enumerator.
+    #
+    # @overload each_enum(&block)
+    #   When called with a block, yields each item to the block and returns `nil`.
+    #   @yieldparam enum [Extension] Yields an extension to the block.
+    #   @return [void]
+    def each_extension
+      #noinspection RubyYardReturnMatch
+      return enum_for(__method__) unless block_given?
+      @extensions.each { |item| yield item }
+      nil
+    end
+
+    ##
+    # Download the latest version of the OpenGL registry to the specified file.
+    #
+    # @param path [String] The path where the file will be saved.
+    #
+    # @return [Boolean] `true` on success, otherwise `false` if an error occurred.
+    def self.download(path)
+      begin
+        URI.open('https://raw.githubusercontent.com/KhronosGroup/OpenGL-Registry/master/xml/gl.xml') do |io|
+          FileUtils.mv(io.path, path)
+        end
+        return true
+      rescue
+        return false
+      end
+    end
+
+    ##
+    # Compares the registry at the specified path to the current registry version and returns value indicating if there
+    # is a newer version available.
+    #
+    # @param path [String] The path to a registry file to test.
+    #
+    # @return [Boolean] `true` if a newer version is available, otherwise `false` if file is current and/or an error
+    #   occurred.
+    #
+    # @note This method is not guaranteed to be accurate, it only uses the timestamps in the file's metadata, which
+    #   could be inaccurate due to file copying, system time changes, creating from different source, etc.
+    def self.outdated?(path)
+
+      return false unless path && File.exist?(path)
+
+      begin
+        uri = URI('https://api.github.com/repos/KhronosGroup/OpenGL-Registry/commits?path=xml/gl.xml')
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 3, read_timeout: 5) do |http|
+
+          req = Net::HTTP::Get.new(uri)
+          response = http.request(req)
+
+          if response.code == '200'
+            json = JSON.parse(response.body, symbolize_names: true)
+            commit = DateTime.parse(json.first[:commit][:author][:date]).to_time
+            return File.mtime(path) < commit
+          end
+
+        end
+      rescue
+        warn('failed to query current registry version')
+        return false
+      end
+    end
+
+    private
+
+    def initialize(root)
+      raise ArgumentError, 'root cannot be nil' unless root
+
+      @groups = []
+      root.locate('enums').each do |enum|
+        next unless enum.is_a?(Ox::Element)
+        @groups << Group.new(enum)
+      end
+
+      @functions = []
+      root.locate('commands/command').each do |function|
+        next unless function.is_a?(Ox::Element)
+        @functions << Function.new(function)
+      end
+
+      @features = []
+      root.locate('feature').each do |feature|
+        next unless feature.is_a?(Ox::Element)
+        @features << FeatureGroup.new(feature)
+      end
+
+      @extensions = []
+      root.locate('extensions/extension').each do |extension|
+        next unless extension.is_a?(Ox::Element)
+        @extensions << Extension.new(extension)
+      end
+    end
+  end
+end
+
+registry = GL::Registry.load('/code/ruby/khronos-temp/gl.xml')
+spec = GL::Spec.new(registry, :gl, 4.3, :compatibility)
+
+p spec.enums.size