diff --git a/docs/_includes/anchor_links.html b/docs/_includes/anchor_links.html
index 8f0f510..880b9d2 100644
--- a/docs/_includes/anchor_links.html
+++ b/docs/_includes/anchor_links.html
@@ -4,9 +4,9 @@
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + header.id;
+ anchor.innerHTML = "⤤"
- header.parentNode.insertBefore(anchor, header);
- anchor.appendChild(header);
+ header.appendChild(anchor);
};
var link_anchors = function(level, parent) {
@@ -23,7 +23,7 @@
document.addEventListener('DOMContentLoaded', () => {
var main = document.getElementsByClassName("main")[0];
- for(var i = 2; i < 4; i++) {
+ for(var i = 2; i < 5; i++) {
link_anchors(i, main);
}
});
diff --git a/docs/_sass/main.scss b/docs/_sass/main.scss
index 8f27960..6da17f4 100644
--- a/docs/_sass/main.scss
+++ b/docs/_sass/main.scss
@@ -56,7 +56,6 @@ header {
table {
border-collapse: collapse;
- margin: 25px 0;
font-size: 0.9em;
box-shadow: 0 0 20px $shadow-colour;
@@ -89,14 +88,8 @@ table {
}
.function {
- box-shadow: 0 0 20px $shadow-colour;
- margin-bottom: 1em;
-
- .header-link {
- text-decoration: none;
- }
-
h3 {
+ margin: 0;
background-color: $table-border;
color: #fff;
padding: 2px;
@@ -105,40 +98,79 @@ table {
}
.content {
- padding: 5px;
-
- h4 { margin-bottom: 0; }
+ padding: .5em .5em;
- ul {
- list-style-type: none;
- margin: 0;
- padding: 1em;
+ p {
+ margin-top: 0;
}
}
}
+.function, .method {
+ box-shadow: 0 0 20px $shadow-colour;
+ margin: .5em 0;
+
+ h4 {
+ margin: 0;
+ padding: 0;
+ border-bottom: 1px solid $shadow-colour;
+ }
+ h5 { margin-bottom: 0; }
+
+ ul {
+ list-style-type: none;
+ margin: 0;
+ margin-top: 5px;
+ padding: 0;
+ }
+}
+
.object {
+ margin-top: 1em;
+
.header-link { text-decoration: none; }
h3 {
background-color: $table-border;
color: #fff;
+ margin-top: 0;
padding: 2px;
border-top-left-radius: 5px;
border-top-right-radius: 5px;
}
- .method {
- box-shadow: 0 0 20px $shadow-colour;
- margin: .5em 0;
+ .content {
+ border: 1px solid $shadow-colour;
padding: .5em .5em;
- h4 { margin-bottom: 0; }
+ .method {
+ padding: .5em .5em;
+ }
- ul {
- list-style-type: none;
- margin: 0;
- padding: 1em;
+ p {
+ margin-top: 0;
}
}
}
+
+.header-link {
+ margin-left: .5em;
+}
+
+.structure {
+ border-bottom: 2px solid $shadow-colour;
+ padding-bottom: 1em;
+
+ ul {
+ margin: 0;
+ }
+ h5 {
+ margin-bottom: 0;
+ }
+}
+
+.enum {
+ p {
+ margin-top: .25em;
+ }
+}
diff --git a/scripts/api_doc_generator.rb b/scripts/api_doc_generator.rb
index 1d06693..31ab544 100755
--- a/scripts/api_doc_generator.rb
+++ b/scripts/api_doc_generator.rb
@@ -86,14 +86,23 @@ def gen_header(f, name, length = 2)
f.puts ""
end
-def gen_table(f, name, values, info, &block)
+def gen_linked_header(f, prefix, name, suffix, lvl, id_kind, &block)
+ prefix = "#{prefix} " unless prefix.empty?
+ suffix = " #{suffix}" unless suffix.empty?
+
+ gen_header(f,
+ "#{prefix}#{block.call(name)}#{suffix} {##{id_kind}-#{name.CamelCase}}",
+ lvl)
+end
+
+def gen_table(f, lang, name, values, info, &block)
f.puts ""
f.puts "| Value | Description |"
f.puts "|:------|:------------|"
values.each do |v|
vn = v['name']
puts "Unable to find value for #{name} :: #{vn}" unless info.has_key?(vn)
- f.puts "| `#{block.call(vn)}` | #{info[vn].strip} |"
+ f.puts "| `#{block.call(vn)}` | #{substitute(lang, info[vn].strip)} |"
end
f.puts ""
end
@@ -125,13 +134,17 @@ def get_info(type, name)
info
end
+def gen_anchor(type)
+ "#{$kinds[type]}-#{type.CamelCase}"
+end
+
def gen_type_link(prefix, page, type)
return "void" if type.nil?
if $native_types.has_key?(type)
type
else
- "[#{prefix}#{type.CamelCase}]({{ '#{page}##{$kinds[type]}-#{type.CamelCase}' | relative_url }})"
+ "[#{prefix}#{type.CamelCase}]({{ '#{page}##{gen_anchor(type)}' | relative_url }})"
end
end
@@ -143,12 +156,15 @@ def gen_c_type_link(type)
gen_type_link("WGPU", "/api/c.html", type)
end
-def emit_type(type, &block)
+def emit_type(f, type, &block)
order_by_name(@categories[type]).each do |k|
name = k['name']
info = get_info(type, name)
- block.call(k, name, info)
+
+ emit_div_block(f, type) do
+ block.call(k, name, info)
+ end
end
end
@@ -163,19 +179,13 @@ def emit_div_block(f, name, &block)
def emit_params(f, args, &block)
f.write "("
args.each_with_index do |a, idx|
- f.write ", " if idx > 0
+ f.write "," if idx > 0
+ f.write "
"
f.write block.call(a)
end
f.puts ")"
end
-def gen_linked_header(f, prefix, name, suffix, id_kind, &block)
- prefix = "#{prefix} " unless prefix.empty?
- suffix = " #{suffix}" unless suffix.empty?
-
- gen_header(f, "#{prefix}#{block.call(name.CamelCase)}#{suffix} {##{id_kind}-#{name.CamelCase}}", 3)
-end
-
def gen_list(f, list, &block)
list.each do |name|
f.puts " * #{block.call(name)}"
@@ -225,17 +235,30 @@ def substitute(lang, str)
str.gsub(/%%(.*?)%%/) do |m|
cmd = $1.strip!
- if lang == "cpp"
- if cmd == 'null'
- "nullptr"
+ if cmd =~ /method\(([^,]*),\s+([^\)]*)\)/
+ obj = $1
+ method = $2
+
+ display_name = if lang == "cpp"
+ "#{obj.CamelCase}::#{method.CamelCase}"
else
- gen_cpp_type_link(cmd)
+ "wgpu#{obj.CamelCase}#{method.CamelCase}"
end
+
+ "[#{display_name}](##{gen_anchor(obj)}-#{method.CamelCase})"
else
- if cmd == 'null'
- "NULL"
+ if lang == "cpp"
+ if cmd == 'null'
+ "nullptr"
+ else
+ gen_cpp_type_link(cmd)
+ end
else
- gen_c_type_link(cmd)
+ if cmd == 'null'
+ "NULL"
+ else
+ gen_c_type_link(cmd)
+ end
end
end
end
@@ -254,7 +277,7 @@ def emit_value_or_warning(f, lang, info, value, name, default="")
def emit_args(f, lang, src_name, args, info)
return if args.nil? || args.empty?
- gen_header(f, "Arguments", 4)
+ gen_header(f, "Arguments", 5)
args.each do |arg|
arg_name = arg['name']
@@ -294,10 +317,10 @@ def gen_cpp_constants(f)
def gen_cpp_enums(f)
gen_header(f, "Enums")
- emit_type('enum') do |e, name, info|
- gen_linked_header(f, 'enum class', name, '', 'enum') { |n| n }
+ emit_type(f, 'enum') do |e, name, info|
+ gen_linked_header(f, 'enum class', name, '', 3, 'enum') { |n| n.CamelCase }
gen_description_and_ref(f, info)
- gen_table(f, name, e['values'], info['values']) { |n| n.CamelCase }
+ gen_table(f, "cpp", name, e['values'], info['values']) { |n| n.CamelCase }
end
end
@@ -309,35 +332,33 @@ def gen_cpp_bitmasks(f)
operators in order to use them as bitmasks.
HERE
- emit_type('bitmask') do |b, name, info|
- gen_linked_header(f, 'enum class', name, '[bitmask]', 'bitmask') { |n| n }
+ emit_type(f, 'bitmask') do |b, name, info|
+ gen_linked_header(f, 'enum class', name, '[bitmask]', 3, 'bitmask') { |n| n.CamelCase }
gen_description_and_ref(f, info)
- gen_table(f, name, b['values'], info['values']) { |n| n.CamelCase }
+ gen_table(f, "cpp", name, b['values'], info['values']) { |n| n.CamelCase }
end
end
def gen_cpp_function(f)
gen_header(f, "Functions")
- emit_type('function') do |func, name, info|
- emit_div_block(f, 'function') do
- gen_linked_header(f, '', name, '', 'function') { |n| n }
+ emit_type(f, 'function') do |func, name, info|
+ gen_linked_header(f, '', name, '', 3, 'function') { |n| n.CamelCase }
- emit_div_block(f, 'content') do
- gen_description_and_ref(f, info)
+ emit_div_block(f, 'content') do
+ gen_description_and_ref(f, info)
- emit_div_block(f, 'signature') do
- f.write "#{gen_cpp_type_link(func['returns'])} #{name.CamelCase}"
- emit_params(f, func['args']) { |p| gen_cpp_member(p) }
- end
+ emit_div_block(f, 'signature') do
+ f.write "#{gen_cpp_type_link(func['returns'])} #{name.CamelCase}"
+ emit_params(f, func['args']) { |p| gen_cpp_member(p) }
+ end
- gen_header(f, 'Returns', 4)
- emit_value_or_warning(f, "cpp", info['returns'], func['returns'], func['name'])
- f.puts ""
- f.puts ""
+ gen_header(f, 'Returns', 5)
+ emit_value_or_warning(f, "cpp", info['returns'], func['returns'], func['name'])
+ f.puts ""
+ f.puts ""
- emit_args(f, "cpp", func['name'], func['args'], info)
- end
+ emit_args(f, "cpp", func['name'], func['args'], info)
end
end
end
@@ -345,9 +366,9 @@ def gen_cpp_function(f)
def gen_cpp_function_pointers(f)
gen_header(f, "Function Pointers")
- emit_type('function pointer') do |func, name, info|
+ emit_type(f, 'function pointer') do |func, name, info|
emit_div_block(f, 'function') do
- gen_linked_header(f, '', name, '', 'function-pointer') { |n| n }
+ gen_linked_header(f, '', name, '', 3, 'function-pointer') { |n| n.CamelCase }
emit_div_block(f, 'content') do
gen_description_and_ref(f, info)
@@ -366,8 +387,8 @@ def gen_cpp_function_pointers(f)
def gen_cpp_structures(f)
gen_header(f, "Structures")
- emit_type('structure') do |struct, name, info|
- gen_linked_header(f, 'struct', name, '', 'structure') { |n| n }
+ emit_type(f, 'structure') do |struct, name, info|
+ gen_linked_header(f, 'struct', name, '', 3, 'structure') { |n| n.CamelCase }
if !struct['members'].empty? || ['in', 'out'].include?(struct['extensible']) ||
['in', 'out'].include?(struct['chained'])
@@ -403,12 +424,12 @@ def gen_cpp_structures(f)
end
if !$chain_in[name].nil?
- gen_header(f, 'Chainable Structures', 4)
+ gen_header(f, 'Chainable Structures', 5)
gen_list(f, $chain_in[name]) { |n| gen_cpp_type_link(n) }
end
if !$chain_in_parents[name].nil?
- gen_header(f, 'Chain Parent Structures', 4)
+ gen_header(f, 'Chain Parent Structures', 5)
gen_list(f, $chain_in_parents[name]) { |n| gen_cpp_type_link(n) }
end
end
@@ -417,31 +438,39 @@ def gen_cpp_structures(f)
def gen_cpp_classes(f)
gen_header(f, "Classes")
- emit_type('object') do |klass, name, info|
+ emit_type(f, 'object') do |klass, name, info|
emit_div_block(f, 'object') do
- gen_linked_header(f, 'class', name, '', 'class') { |n| n }
- gen_description_and_ref(f, info)
+ gen_linked_header(f, 'class', name, '', 3, 'class') { |n| n.CamelCase }
- (klass['methods'] || []).sort { |a, b| a['name'] <=> b['name'] }.each do |method|
- emit_div_block(f, 'method') do
-
- method_info = (info['methods'] || {})[method['name']] || {}
- gen_description_and_ref(f, method_info)
-
- emit_div_block(f, 'signature') do
- f.write "#{gen_cpp_type_link(method['returns'])} #{method['name'].CamelCase}"
- emit_params(f, method['args'] || []) { |p| gen_cpp_member(p) }
- f.puts ""
- end
+ emit_div_block(f, 'content') do
+ emit_div_block(f, 'description') do
+ gen_description_and_ref(f, info)
+ end
- if !method['returns'].nil? && method['returns'] != 'void'
- gen_header(f, "Returns", 4)
- emit_value_or_warning(f, "cpp", method_info['returns'],
- method['returns'], method['name'])
- f.puts ""
+ (klass['methods'] || []).sort { |a, b| a['name'] <=> b['name'] }.each do |method|
+ emit_div_block(f, 'method') do
+ gen_linked_header(f, '', method['name'], '', 4, "#{gen_anchor(name)}") do |n|
+ n.CamelCase
+ end
+
+ method_info = (info['methods'] || {})[method['name']] || {}
+ gen_description_and_ref(f, method_info)
+
+ emit_div_block(f, 'signature') do
+ f.write "#{gen_cpp_type_link(method['returns'])} #{method['name'].CamelCase}"
+ emit_params(f, method['args'] || []) { |p| gen_cpp_member(p) }
+ f.puts ""
+ end
+
+ if !method['returns'].nil? && method['returns'] != 'void'
+ gen_header(f, "Returns", 5)
+ emit_value_or_warning(f, "cpp", method_info['returns'],
+ method['returns'], method['name'])
+ f.puts ""
+ end
+
+ emit_args(f, "cpp", method['name'], method['args'], method_info)
end
-
- emit_args(f, "cpp", method['name'], method['args'], method_info)
end
end
end
@@ -513,10 +542,10 @@ def gen_c_constants(f)
def gen_c_enums(f)
gen_header(f, "Enums")
- emit_type('enum') do |e, name, info|
- gen_linked_header(f, 'enum', name, '', 'enum') { |n| "WGPU#{n}" }
+ emit_type(f, 'enum') do |e, name, info|
+ gen_linked_header(f, 'enum', name, '', 3, 'enum') { |n| "WGPU#{n.CamelCase}" }
gen_description_and_ref(f, info)
- gen_table(f, name, e['values'], info['values']) do |n|
+ gen_table(f, "c", name, e['values'], info['values']) do |n|
"WGPU#{name.CamelCase}_#{n.CamelCase}"
end
end
@@ -531,10 +560,10 @@ def gen_c_bitmasks(f)
signatures.
HERE
- emit_type('bitmask') do |b, name, info|
- gen_linked_header(f, 'enum', name, '[bitmask]', 'bitmask') { |n| "WGPU#{n}" }
+ emit_type(f, 'bitmask') do |b, name, info|
+ gen_linked_header(f, 'enum', name, '[bitmask]', 2, 'bitmask') { |n| "WGPU#{n.CamelCase}" }
gen_description_and_ref(f, info)
- gen_table(f, name, b['values'], info['values']) do |n|
+ gen_table(f, "c", name, b['values'], info['values']) do |n|
"WGPU#{name.CamelCase}_#{n.CamelCase}"
end
f.puts "`typedef WGPUFlags WGPU#{name.CamelCase}Flags`"
@@ -545,25 +574,23 @@ def gen_c_bitmasks(f)
def gen_c_function(f)
gen_header(f, "Functions")
- emit_type('function') do |func, name, info|
- emit_div_block(f, 'function') do
- gen_linked_header(f, '', name, '', 'function') { |n| "wgpu#{n}" }
+ emit_type(f, 'function') do |func, name, info|
+ gen_linked_header(f, '', name, '', 3, 'function') { |n| "wgpu#{n.CamelCase}" }
- emit_div_block(f, 'content') do
- gen_description_and_ref(f, info)
+ emit_div_block(f, 'content') do
+ gen_description_and_ref(f, info)
- emit_div_block(f, 'signature') do
- f.write "#{gen_c_type_link(func['returns'])} wgpu#{name.CamelCase}"
- emit_params(f, func['args']) { |p| gen_c_member(p) }
- end
+ emit_div_block(f, 'signature') do
+ f.write "#{gen_c_type_link(func['returns'])} wgpu#{name.CamelCase}"
+ emit_params(f, func['args']) { |p| gen_c_member(p) }
+ end
- gen_header(f, 'Returns', 4)
- emit_value_or_warning(f, "c", info['returns'], func['returns'], func['name'])
- f.puts ""
- f.puts ""
+ gen_header(f, 'Returns', 5)
+ emit_value_or_warning(f, "c", info['returns'], func['returns'], func['name'])
+ f.puts ""
+ f.puts ""
- emit_args(f, "c", func['name'], func['args'], info)
- end
+ emit_args(f, "c", func['name'], func['args'], info)
end
end
end
@@ -571,9 +598,9 @@ def gen_c_function(f)
def gen_c_function_pointers(f)
gen_header(f, "Function Pointers")
- emit_type('function pointer') do |func, name, info|
+ emit_type(f, 'function pointer') do |func, name, info|
emit_div_block(f, 'function') do
- gen_linked_header(f, '', name, '', 'function-pointer') { |n| "WGPU#{n}" }
+ gen_linked_header(f, '', name, '', 3, 'function-pointer') { |n| "WGPU#{n.CamelCase}" }
emit_div_block(f, 'content') do
gen_description_and_ref(f, info)
@@ -592,8 +619,8 @@ def gen_c_function_pointers(f)
def gen_c_structures(f)
gen_header(f, "Structures")
- emit_type('structure') do |struct, name, info|
- gen_linked_header(f, 'struct', name, '', 'structure') { |n| "WGPU#{n}" }
+ emit_type(f, 'structure') do |struct, name, info|
+ gen_linked_header(f, 'struct', name, '', 3, 'structure') { |n| "WGPU#{n.CamelCase}" }
if !struct['members'].empty? || ['in', 'out'].include?(struct['extensible']) ||
['in', 'out'].include?(struct['chained'])
@@ -621,12 +648,12 @@ def gen_c_structures(f)
end
if !$chain_in[name].nil?
- gen_header(f, 'Chainable Structures', 4)
+ gen_header(f, 'Chainable Structures', 5)
gen_list(f, $chain_in[name]) { |n| gen_c_type_link(n) }
end
if !$chain_in_parents[name].nil?
- gen_header(f, 'Chain Parent Structures', 4)
+ gen_header(f, 'Chain Parent Structures', 5)
gen_list(f, $chain_in_parents[name]) { |n| gen_c_type_link(n) }
end
end
@@ -635,43 +662,54 @@ def gen_c_structures(f)
def gen_c_objects(f)
gen_header(f, "Methods")
- emit_type('object') do |klass, name, info|
+ emit_type(f, 'object') do |klass, name, info|
emit_div_block(f, 'object') do
- gen_linked_header(f, 'Methods of', name, '', 'class') { |n| "WGPU#{n}" }
- gen_description_and_ref(f, info)
+ gen_linked_header(f, 'Methods of', name, '', 3, 'class') { |n| "WGPU#{n.CamelCase}" }
- methods = (klass['methods'] || [])
- methods.push({
- "name" => "reference"
- })
- methods.push({
- "name" => "release"
- })
-
- methods.sort { |a, b| a['name'] <=> b['name'] }.each do |method|
- emit_div_block(f, 'method') do
- args = method['args'] || []
- args.unshift({
- "name" => klass['name'],
- "type" => klass['name']
- })
-
- method_info = (info['methods'] || {})[method['name']] || {}
- gen_description_and_ref(f, method_info)
-
- emit_div_block(f, 'signature') do
- f.write "#{gen_c_type_link(method['returns'])} wgpu#{klass['name'].CamelCase}#{method['name'].CamelCase}"
- emit_params(f, args) { |p| gen_c_member(p) }
- f.puts ""
- end
+ emit_div_block(f, 'content') do
+ emit_div_block(f, 'description') do
+ gen_description_and_ref(f, info)
+ end
- if !method['returns'].nil? && method['returns'] != 'void'
- gen_header(f, "Returns", 4)
- emit_value_or_warning(f, "c", method_info['returns'], method['returns'], method['name'])
- f.puts ""
+ methods = (klass['methods'] || [])
+ methods.push({
+ "name" => "reference"
+ })
+ methods.push({
+ "name" => "release"
+ })
+
+ methods.sort { |a, b| a['name'] <=> b['name'] }.each do |method|
+ emit_div_block(f, 'method') do
+ args = method['args'] || []
+ args.unshift({
+ "name" => klass['name'],
+ "type" => klass['name']
+ })
+
+ to_method_name = lambda { |n| "wgpu#{klass['name'].CamelCase}#{n.CamelCase}" }
+ gen_linked_header(f, '', method['name'], '', 4, "#{gen_anchor(name)}") do |n|
+ to_method_name.call(n)
+ end
+
+ method_info = (info['methods'] || {})[method['name']] || {}
+ gen_description_and_ref(f, method_info)
+
+ emit_div_block(f, 'signature') do
+ f.write "#{gen_c_type_link(method['returns'])} #{to_method_name.call(method['name'])}"
+ emit_params(f, args) { |p| gen_c_member(p) }
+ f.puts ""
+ end
+
+ if !method['returns'].nil? && method['returns'] != 'void'
+ gen_header(f, "Returns", 5)
+ emit_value_or_warning(
+ f, "c", method_info['returns'], method['returns'], method['name'])
+ f.puts ""
+ end
+
+ emit_args(f, "c", method['name'], args, method_info)
end
-
- emit_args(f, "c", method['name'], args, method_info)
end
end
end
diff --git a/src/api.yaml b/src/api.yaml
index 9c97690..8f9b9a5 100644
--- a/src/api.yaml
+++ b/src/api.yaml
@@ -77,6 +77,58 @@ enum:
openGL: The OpenGL backend
openGLES: The OpenGL ES backend
+ blend factor:
+ description: >
+ Determines how a blend factor is calculated. This factor will be combined
+ with the original color based on the selected blend operation.
+ ref:
+ name: GPUBlendFactor
+ anchor: '#enumdef-gpublendfactor'
+ values:
+ zero: >
+ Factor is set to zero.
+ `(0, 0, 0, 0)`
+ one: >
+ Factor is set to one.
+ `(1, 1, 1, 1)`
+ src: >
+ Factor is set to the source values.
+ `(R_src, G_src, B_src, A_src)`
+ one minus src: >
+ Factor is set to one minus source value.
+ `(1 - R_src, 1 - G_src, 1 - B_src, 1 - A_src)`
+ src alpha: >
+ Factor is set to the source alpha value.
+ `(A_src, A_src, A_src, A_src)`
+ src alpha saturated: >
+ Factor is set to the source alpha value.
+ `(A_src, A_src, A_src, A_src)`
+ one minus src alpha: >
+ Factor is set to one minus the source alpha value.
+ `(1 - A_src, 1 - A_src, 1 - A_src, 1 - A_src)`
+ dst: >
+ Factor is set to the destination value.
+ `(R_dst, G_dst, B_dst, A_dst)`
+ one minus dst: >
+ Factor is set to one minus destination value.
+ `(1 - R_dst, 1 - G_dst, 1 - B_dst, 1 - A_dst)`
+ dst alpha: >
+ Factor is set to the destinatinon alpha value.
+ `(A_dst, A_dst, A_dst, A_dst)`
+ one minus dst alpha: >
+ Factor is set to one minus the destionation alpha value.
+ `(1 - A_dst, 1 - A_dst, 1 - A_dst, 1 - A_dst)`
+ constant: >
+ Factor is set to the constant value.
+ (See %% method(render pass encoder, set blend constant) %%
+ for setting of the constant value.)
+ `(R_const, G_const, B_const, A_const)`
+ one minus constant: >
+ Factor is set to one minus the constant value.
+ (See %% method(render pass encoder, set blend constant) %%
+ for setting of the constant value.)
+ `(1 - R_const, 1 - G_const, 1 - B_const, 1 - A_const)`
+
bitmask:
texture usage:
description: Determine how a GPUTexture maybe be used after creation.