Doc/alpha 2

DesignNotes.md

@@ -2,6 +2,10 @@
 
 vk.xml schema documentation: [https://registry.khronos.org/vulkan/specs/1.3/registry.html]
 
+This file documents some of the thought process and tasks during development of vk-gen. This file remains for historical
+reference, but the codebase has grown beyond what is detailed here and you should not assume that this file describes
+precisely how the tool works. 
+
 ## vk.xml and exceptions.json
 There are several significant barriers to generating the Go-binding for Vulkan:
 

README.md

@@ -44,6 +44,3 @@ issue/PR will clean this up, but they don't hurt anything at the moment.
   anything that resolves to a constant in Go, though most typically it will be an integer value (represented as a
   string). The value should be the aligned (?) data size in bytes of the largest member of the union. 
 
-## TODO
-
-* VkDescriptorDataEXT - Pointer members are being recognized as slices, compile error on slice copy.

def/array_type.go

@@ -19,9 +19,6 @@ func (t *arrayType) Category() TypeCategory { return CatArray }
 func (t *arrayType) Resolve(tr TypeRegistry, vr ValueRegistry) *IncludeSet {
 
 	return t.resolvedPointsAtType.Resolve(tr, vr)
-	// is := includeSet{
-	// 	includeTypeNames: ,
-	// }
 }
 
 func (t *arrayType) IsIdenticalPublicAndInternal() bool {
@@ -62,53 +59,19 @@ func (t *arrayType) PrintVulkanizeContent(forMember *structMember, preamble io.W
 		fmt.Fprintf(preamble, "copy(rval.%s[:], s.%s)\n", forMember.InternalName(), forMember.PublicName())
 
 		structMemberAssignment = ""
-	} else {
-		// 		pre := fmt.Sprintf(sliceTranslationTemplate,
-		// 			forMember.InternalName(), t.resolvedPointsAtType.InternalName(), forMember.PublicName(),
-		// 			forMember.PublicName(),
-		// 			forMember.InternalName(), t.resolvedPointsAtType.TranslateToInternal("v"),
-		// 		)
-		// 		fmt.Fprint(preamble, pre)
-		// 		structMemberAssignment = "&(sl_" + forMember.InternalName() + "[0])"
-		// 	}
-		// } else {
-		// 	if t.resolvedPointsAtType.IsIdenticalPublicAndInternal() {
-		// 		structMemberAssignment = fmt.Sprintf("(%s)(s.%s)", t.InternalName(), forMember.PublicName())
-		// 	} else {
-		// 		structMemberAssignment = t.resolvedPointsAtType.TranslateToInternal("s." + forMember.PublicName())
-		// 		if t.resolvedPointsAtType.Category() == CatStruct {
-		// 			structMemberAssignment = strings.TrimLeft(structMemberAssignment, "*")
-		// 		}
-		// 	}
 	}
+
 	return
 }
 func (t *arrayType) PrintGoifyContent(forMember *structMember, preamble, epilogue io.Writer) (structMemberAssignment string) {
-	structMemberAssignment = "0 /* TODO ARRAY NOT HANDLED */"
-
-	// if t.resolvedPointsAtType.IsIdenticalPublicAndInternal() {
-	// if this is an array to types that are "IsIdentical..." then just
-	// copy the array as a block and move on
-	// fmt.Fprintf(epilogue, t.TranslateToPublic("s."+forMember.InternalName()))
 
 	if t.resolvedPointsAtType.InternalName() == "byte" {
-		// fmt.Fprintf(epilogue, "rval.%s = nullTermBytesToString(s.%s[:])\n", forMember.PublicName(), forMember.InternalName())
 		structMemberAssignment = fmt.Sprintf("nullTermBytesToString(s.%s[:])", forMember.InternalName())
 		return
 	}
 
 	fmt.Fprintf(epilogue, "copy(rval.%s[:], s.%s[:])\n", forMember.PublicName(), forMember.InternalName())
 
 	structMemberAssignment = ""
-	// } else {
-	// 	structMemberAssignment = t.resolvedPointsAtType.TranslateToPublic("s." + forMember.InternalName())
-	// }
 	return
 }
-
-// const sliceTranslationTemplate string = `
-//   sl_%s := make([]%s, len(s.%s))
-//   for i, v := range s.%s {
-// 	sl_%s[i] = %s
-//   }
-// `

def/base_type.go

@@ -48,7 +48,6 @@ func (t *baseType) PrintPublicDeclaration(w io.Writer) {
 	t.PrintDocLink(w)
 	if t.publicTypeNameOverride != "" {
 		return
-		// fmt.Fprintf(w, "type %s %s\n", t.PublicName(), t.publicTypeNameOverride)
 	} else {
 		fmt.Fprintf(w, "type %s %s\n", t.PublicName(), t.resolvedUnderlyingType.InternalName())
 	}

def/command_type.go

@@ -22,14 +22,12 @@ type commandType struct {
 
 	parameters []*commandParam
 
-	bindingParams []*commandParam
-	returnParams  []*commandParam
-	// identicalInternalExternal bool
-	// isReturnedOnly            bool
+	bindingParams     []*commandParam
+	returnParams      []*commandParam
 	bindingParamCount int
 }
 
-// Two exceptions to camelCase rules used for function return params
+// Exceptions to camelCase rules used for function return params
 func init() {
 	// rename return params to avoid typenames
 	strcase.ConfigureAcronym("Result", "r")
@@ -73,18 +71,12 @@ func (t *commandType) Resolve(tr TypeRegistry, vr ValueRegistry) *IncludeSet {
 		}
 	}
 
-	// if t.publicName == "" { // publicName may already be set by an entry from exceptions.json
-	// 	t.publicName = RenameIdentifier(t.registryName)
-	// }
-
 	for _, p := range t.parameters {
 		p.parentCommand = t
 
 		iset.MergeWith(p.Resolve(tr, vr))
 	}
 
-	// t.identicalInternalExternal = t.determineIdentical()
-
 	iset.ResolvedTypes[t.registryName] = t
 
 	t.isResolved = true
@@ -128,19 +120,9 @@ func (t *commandType) PrintPublicDeclaration(w io.Writer) {
 		fmt.Fprintf(w, "var %s = %s\n\n", t.PublicName(), t.resolvedAliasType.PublicName())
 		return
 	}
-	// funcReturnNames, funcReturnTypes := &strings.Builder{}, &strings.Builder{}
 
 	preamble, epilogue, outputTranslation := &strings.Builder{}, &strings.Builder{}, &strings.Builder{}
 
-	// var doubleCallArrayParam *commandParam
-	// var doubleCallArrayTypeName string
-
-	// var isDoubleCallCommand bool
-
-	// for _, p := range t.bindingParams {
-	// 	funcParams = funcParams + ", " + p.publicName + " " + p.resolvedType.PublicName()
-	// }
-
 	funcReturnParams := make([]*commandParam, 0)
 	var trampolineReturns *commandParam
 	funcInputParams := make([]*commandParam, 0)
@@ -154,6 +136,7 @@ func (t *commandType) PrintPublicDeclaration(w io.Writer) {
 		trampolineReturns = retParam
 	}
 
+	// Iterative dev process:
 	// Start with a simple output scenario - vkEndCommandBuffer takes a single
 	// input (ignore for the moment) and returns a VkResult
 	// Deal with simple inputs, like handles and primitive/scalar types
@@ -167,20 +150,6 @@ func (t *commandType) PrintPublicDeclaration(w io.Writer) {
 		// - Go return values
 		// - Trampoline parameters, with or without translation
 
-		// if p.isDoubleCallArray {
-		// 	isDoubleCallCommand = true
-		// 	// This gets saved for later printing the calls
-		// 	doubleCallArrayParam = p
-
-		// 	fmt.Fprintf(funcReturnNames, ", %s", p.publicName)
-		// 	retSliceType := p.resolvedType.(*pointerType).resolvedPointsAtType
-		// 	fmt.Fprintf(funcReturnTypes, "[]%s", retSliceType.PublicName())
-		// } else if p.isOutput {
-		// 	fmt.Fprintf(funcReturnNames, ", %s", p.publicName)
-		// 	fmt.Fprintf(funcReturnTypes, ", %s", p.resolvedType.PublicName())
-		// } else {
-		// 	fmt.Fprintf(funcParams, ", %s %s", p.publicName, p.resolvedType.PublicName())
-		// }
 		if p.resolvedType.Category() == CatPointer {
 			paramTypeAsPointer := p.resolvedType.(*pointerType)
 
@@ -380,8 +349,6 @@ func (t *commandType) PrintPublicDeclaration(w io.Writer) {
 							stringParts := strings.Split(p.lenSpec, "->")
 							translatedLenMember := stringParts[0] + "." + stringParts[1]
 
-							// fmt.Fprintf(preamble, "  sl_%s := make([]%s, %s)\n", p.internalName, p.resolvedType.InternalName(), translatedLenMember)
-							// fmt.Fprintf(preamble, "  %s := &sl_%s[0]\n", p.internalName, p.internalName)
 							fmt.Fprintf(preamble, "  %s = make(%s, %s)\n", p.publicName, p.resolvedType.PublicName(), translatedLenMember)
 							fmt.Fprintf(preamble, "  %s := &%s[0]\n", p.internalName, p.publicName)
 
@@ -537,47 +504,8 @@ func (t *commandType) printTrampolineCall(w io.Writer, trampParams []*commandPar
 	}
 }
 
-func (t *commandType) PrintInternalDeclaration(w io.Writer) {
-
-	// var preamble, structDecl, epilogue strings.Builder
-
-	// if t.identicalInternalExternal {
-	// 	fmt.Fprintf(w, "type %s = %s\n", t.InternalName(), t.PublicName())
-	// } else {
-	// 	if t.isReturnedOnly {
-	// 		fmt.Fprintf(w, "// WARNING - This struct is returned only, which is not yet handled in the binding\n")
-	// 	}
-	// 	// _vk type declaration
-	// 	fmt.Fprintf(w, "type %s struct {\n", t.InternalName())
-	// 	for _, m := range t.members {
-	// 		m.PrintInternalDeclaration(w)
-	// 	}
-
-	// 	fmt.Fprintf(w, "}\n")
-	// }
-
-	// // Vulkanize declaration
-	// // Set required values, like the stype
-	// // Expand slices to pointer and length parameters
-	// // Convert strings, and string arrays
-	// fmt.Fprintf(&preamble, "func (s *%s) Vulkanize() *%s {\n", t.PublicName(), t.InternalName())
-
-	// if t.identicalInternalExternal {
-	// 	fmt.Fprintf(&structDecl, "  rval := %s(*s)\n", t.InternalName())
-	// } else {
-	// 	fmt.Fprintf(&structDecl, "  rval := %s{\n", t.InternalName())
-	// 	for _, m := range t.members {
-	// 		m.PrintVulcDeclarationAsssignment(&preamble, &structDecl, &epilogue)
-	// 	}
-	// 	fmt.Fprintf(&structDecl, "  }\n")
-	// }
-	// fmt.Fprintf(&epilogue, "  return &rval\n")
-	// fmt.Fprintf(&epilogue, "}\n")
-
-	// fmt.Fprint(w, preamble.String(), structDecl.String(), epilogue.String())
-
-	// Goify declaration (if applicable?)
-}
+// There is no internal declaration for commands, this function is empty
+func (t *commandType) PrintInternalDeclaration(w io.Writer) {}
 
 type commandParam struct {
 	registryName string
@@ -658,7 +586,6 @@ func (p *commandParam) Resolve(tr TypeRegistry, vr ValueRegistry) *IncludeSet {
 		if p.isConstParam {
 			if p.lenSpec == "" {
 				p.isInput = true
-				// p.requiresTranslation = !p.resolvedType.IsIdenticalPublicAndInternal()
 
 			} else if p.lenMemberParam != nil {
 				// if this param is a const pointer with a len specifier that maps to

def/define_type.go

@@ -143,13 +143,6 @@ func ReadDefineExceptionsFromJSON(exceptions gjson.Result, tr TypeRegistry, vr V
 
 		tr[entry.RegistryName()] = entry
 
-		// exVal.Get("constants").ForEach(func(ck, cv gjson.Result) bool {
-		// 	newVal := NewConstantValue(ck.String(), cv.String(), key.String())
-
-		// 	vr[newVal.RegistryName()] = newVal
-		// 	return true
-		// })
-
 		return true
 	})
 

def/enum_type.go

@@ -49,7 +49,7 @@ func (t *enumType) PrintPublicDeclaration(w io.Writer) {
 	if len(t.values) > 0 {
 		fmt.Fprint(w, "const (\n")
 		for _, v := range t.values {
-			v.PrintPublicDeclaration(w) // || !v.IsAlias())
+			v.PrintPublicDeclaration(w)
 		}
 		fmt.Fprint(w, ")\n\n")
 	}

def/enum_value.go

@@ -76,7 +76,6 @@ func ReadApiConstantsFromXML(doc *xmlquery.Node, externalType TypeDefiner, tr Ty
 		valDef := NewEnumValueFromXML(externalType, node)
 		valDef.isCore = true
 		vr[valDef.RegistryName()] = valDef
-		// externalType.PushValue(valDef)
 	}
 }
 
@@ -115,8 +114,6 @@ func ReadEnumValuesFromXML(doc *xmlquery.Node, td TypeDefiner, tr TypeRegistry,
 				// VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR
 				// To handle this, we're reading the node and then merging with any val def already in the map
 
-				// valDef.isCore = valDef.extNumber != 0
-
 				if existing, found := vr[valDef.RegistryName()]; found {
 					existingAsEnum := existing.(*enumValue)
 					if valDef.extNumber == 0 {
@@ -243,8 +240,6 @@ func NewUntypedEnumValueFromXML(elt *xmlquery.Node) *extenValue {
 	}
 	rval.comment = elt.SelectAttr("comment")
 
-	// rval.underlyingTypeName = "!none"
-
 	return &rval
 }
 

def/external_type.go

@@ -116,7 +116,6 @@ func NewOrUpdateExternalValueFromJSON(key, value string, td TypeDefiner, tr Type
 	updatedEntry.isCore = true
 
 	vr[key] = updatedEntry
-	// td.PushValue(updatedEntry)
 }
 
 func (t *externalType) Resolve(tr TypeRegistry, vr ValueRegistry) *IncludeSet {

def/generic_type.go

@@ -100,26 +100,6 @@ func (t *genericType) PrintTranslateToInternal(w io.Writer, inputVar, outputVar
 	fmt.Fprintf(w, "%s = %s", outputVar, inputVar)
 }
 
-// func (t *genericType) PrintConstValues(w io.Writer) {
-// 	switch len(t.values) {
-// 	case 0:
-// 		return
-// 	case 1:
-// 		fmt.Fprintln(w)
-// 		fmt.Fprint(w, "const ")
-// 		t.values[0].PrintPublicDeclaration(w, true)
-// 		fmt.Fprintln(w)
-// 	default:
-// 		fmt.Fprintln(w)
-// 		fmt.Fprintln(w, "const (")
-// 		for _, v := range t.values {
-// 			v.PrintPublicDeclaration(w, !v.IsAlias())
-// 		}
-// 		fmt.Fprintln(w, ")")
-// 		fmt.Fprintln(w)
-// 	}
-// }
-
 func (t *genericType) PrintDocLink(w io.Writer) {
 	fmt.Fprintf(w, "// %s: ", t.PublicName())
 	if t.comment != "" {

def/handle_type.go

@@ -84,8 +84,6 @@ func ReadHandleExceptionsFromJSON(exceptions gjson.Result, tr TypeRegistry, vr V
 			newVal.valueString = cv.String()
 			newVal.underlyingTypeName = key.String()
 
-			// newVal := NewEnumValue(ck.String(), cv.String(), key.String())
-
 			vr[newVal.RegistryName()] = &newVal
 			return true
 		})

def/internal_type.go

@@ -44,14 +44,4 @@ func (t *internalType) PrintPublicDeclaration(w io.Writer) {
 	} else {
 		fmt.Fprintf(w, "type %s %s\n", t.PublicName(), t.underlyingType.PublicName())
 	}
-
-	// 	sort.Sort(byValue(t.values))
-
-	// 	if len(t.values) > 0 {
-	// 		fmt.Fprint(w, "const (\n")
-	// 		for _, v := range t.values {
-	// 			v.PrintPublicDeclaration(w)
-	// 		}
-	// 		fmt.Fprint(w, ")\n\n")
-	// 	}
 }

def/name_conversion.go

@@ -12,6 +12,7 @@ func trimVk(s string) string {
 		return s
 	}
 	r := trimRx.FindStringSubmatch(s)
+	// Match References:
 	// r[0] = s
 	// r[1] = pointers
 	// r[2] = Vk, vk, or VK_