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.