class GL::Registry

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

Constants

GL_TYPES

An array of OpenGL type names, as symbols.

VERSION

The current version of the `opengl-registry` gem.

Attributes

extensions[R]

@return [Array<Extension>] a complete collection of all OpenGL extensions.

features[R]

@return [Array<FeatureGroup>] a complete collection of all OpenGL feature groups.

functions[R]

@return [Array<Function>] a complete collection of all OpenGL functions.

groups[R]

@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.

Public Class Methods

download(path) click to toggle source

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.

# File lib/opengl/registry.rb, line 237
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
load(path) click to toggle source

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}.

# File lib/opengl/registry.rb, line 86
def self.load(path)
  doc = Ox.load_file(path, mode: :generic)
  new(doc.root)
end
new(root) click to toggle source
# File lib/opengl/registry.rb, line 285
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
outdated?(path) click to toggle source

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.
# File lib/opengl/registry.rb, line 259
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
parse(xml) click to toggle source

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}.

# File lib/opengl/registry.rb, line 97
def self.parse(xml)
  doc = Ox.load(xml, mode: :generic)
  new(doc.root)
end

Public Instance Methods

api_names() click to toggle source

@return [Array<Symbol>] an array of Symbol objects that represent each defined API in the registry.

# File lib/opengl/registry.rb, line 104
def api_names
  # RubyMine warns that the return value is wrong. It lies.
  #noinspection RubyYardReturnMatch
  @features.map(&:api).uniq
end
each_enum() { |item| ... } click to toggle source

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]
# File lib/opengl/registry.rb, line 150
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
each_extension() { |item| ... } click to toggle source

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]
# File lib/opengl/registry.rb, line 224
def each_extension
  #noinspection RubyYardReturnMatch
  return enum_for(__method__) unless block_given?
  @extensions.each { |item| yield item }
  nil
end
each_feature() { |item| ... } click to toggle source

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]
# File lib/opengl/registry.rb, line 206
def each_feature
  #noinspection RubyYardReturnMatch
  return enum_for(__method__) unless block_given?
  @features.each { |item| yield item }
  nil
end
each_function() { |item| ... } click to toggle source

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]
# File lib/opengl/registry.rb, line 188
def each_function
  #noinspection RubyYardReturnMatch
  return enum_for(__method__) unless block_given?
  @functions.each { |item| yield item }
  nil
end
each_group() { |item| ... } click to toggle source

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]
# File lib/opengl/registry.rb, line 170
def each_group
  #noinspection RubyYardReturnMatch
  return enum_for(__method__) unless block_given?
  @groups.each { |item| yield item }
  nil
end
enums() click to toggle source
# File lib/opengl/registry.rb, line 134
def enums
  #noinspection RubyResolve
  @enums ||= each_enum.to_a
end
profiles(api = nil, version = '1.0') click to toggle source

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.

# File lib/opengl/registry.rb, line 123
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