Vulkan API Tutorial - 2 - Debugging

hello everyone and welcome to this Vulkan API tutorial in this tutorial we're gonna discuss about the debugging in Vulcan as well as what are the layers and what is the loader you might already know that to enable debugging in Vulcan you need to enable validation layers these layers provide error checking memory tracking and we are going to enable a few of those layers what I want to do first here is actually change this VK API version because this is actually a small oversight from my end because you really want to use the newest version of the API so let's make this VK make version the version that most of the Vulcan enables graphics drivers do supports is one point zero point three in my defense all the samples I've seen avoid always put the VK api version here so I just copied that one basically what this makes what did what this does is tells the Valken that this is a version of Vulcan that the driver needs to support so I'll just show you here if I put this version number touch like five or six here and if I run this code the VK creates instance function is going to return VK error incompatible driver this error code that you get from for example creates instance function is a VK result and this gives us quite a bit of information already but there's two types of errors that we need to take into account the first one is validity errors that are caused by invalid usage of the API the second is runtime errors which are basically even if you user APR correctly you might run out of memory for example those errors are reported as we carry salt and return by these functions like create instance what we want to do here is to make sure that we use the API correctly and to do that we need to use validation layers first of all I want to check which layers our system supports or which layers are correctly installed so in it device function before the device queue create info structure and after this all other stuff like physical device Qt family properties and all that I want to make a new section in here the function I want to use is a VK enumerates instance layer properties the first parameter it's a new int and it basically just tells us how many layers there are instance layers the second parameter will return returns a list of VK layer properties we need this function to enumerate our layer instance layers how you do this is just basically creative unsigned integer you int 32 T and I'm gonna call this layer count I'm going to give it a pointer here on the second parameter in this case is a list of VK layer properties structures this function kind of works the same way as VK enumerated physical devices so the first time around we'll put null pointer here and then we create our list with the type of VK layer properties I'm going to call it layer property list with the size of initializing it with the size of layer count then I'm gonna call this function again enumerate instance layer properties and give it a list okay this gives you a list of all the layers currently installed in your system and yeah welkin layers are actually installed in your system and I'll explain a bit more about that later I'm just gonna print everything to the screen here so you can see and then you get to print stuff out actually gonna format this a little bit so CDC out instance layers new line STD see out I'm gonna put a small space in here and print out the layer name I'm gonna put a couple of tabs here and a small spacer and I'm gonna print the layers description and in the line a little bit more formatting as tdz out oh let's just put a our line change here and a breaking trick point here and let's see if this works okay this lists all the layers instance layers by the way not device layers those are two different things so I got these instance layers installed on my system and I did install the render doc and that installed a VK layer render doc capture you might not have this layer and depending on the version of Vulcan you have or the Vulcan header this list might be different okay the next step the device layer properties so I'm just gonna copy this whole thing and change the name of this enumerate instance layer properties to enumerate device layer properties on both of these functions here this actually takes the physical device pointer or handle so GPU here GPU here now changing this name here that should basically do all of it no extra working work needed okay so that got me I think 13 instance layers and 14 actually twelve instance layers and 13 device layers I guess all these layers they enable some sort of debugging I'm going to leave a link to the description of this video which tells what all these layers do for now I think we're just going to use the standard validation this is a kind of like a special layer because it actually enables multiple of these other other layers okay let's continue so what I want to do next is actually enable these layers we are going to make member variables so I like to do this as a vector the type of these is a C type string so const char pointer and this first one I'm going to call instance layer list the second one is again same kind of vector const char t sorry just draw char pointer i'm editing and this is called instance instance extension list Sumathi go STD vector const char again device layer list and the last one is again vector with the same time as the rest and i'll call this device extension list and so i'm gonna tidy up this a little bit and just call it layers and extensions okay in the instance create info there's a few fields in here that you need to put in so instance create into photos enable layer count now this will be the instance layers size and second one will be the actual list so instance creates info PP like pointer to pointer enabled layer names and this will point to the data instance layer data so what does enable layer count mean actually it means how long or how big is this list of enabled layer names then we'll do the same thing for other extensions extension count instance extensions size extension names instance extensions start data okay I'm actually just gonna copy this whole thing because we need to do the exact same thing for the device creates info here except them you know rename a few of these instead of instance layers you're just gonna put the device layers in here like so next I want to create couple of functions here I'm gonna call the first one returning nothing again so void function setup debug second function I'm gonna name I'm gonna name this init debug now the final one will be D in its debug let's create the setup debug function body so basically what I want to do here I'm going to enable these layers so instance layers I'm gonna push back this name and that basically enables the standard validation layer for the instance now we want to do the same thing for the device so device layers push back the same layer name and this should work so let's put our setup function to our constructor as a first function and let's see if this works well it didn't crash and if it did seem to work let's actually put a breakpoint - where is it there create instance function it does say success that's exactly what I wanted I actually want to change this a little bit I just wanted to make sure this actually works the standard validation should work for both of these but because it's a didn't enables quite a few layers and I don't necessarily need all of those layers I'm going to individually enable some layers instance layers push back okay it just keeps ahead a bit a little bit I just added a few of these layers that I want to use and I'm gonna copy all of this to the device and just use device layers for this like this and that should enable only these layers and nothing else so how these layers actually work when you call an instance function or function that uses an instance it's going to go into this one and then this one is going to check all the parameters of it of the command and then it's gonna pass the command to this layer the second layer which in this case is an object tracker after that the object tracker is going to push it up give it to a memory tracker layer which is gonna attract the memory for you and so forth and so forth it's gonna go through all of these layers and after the final one it's going to walk incor now the same thing happens in device layers basically if you call a command and I uses the device it's gonna do the same thing except that in the device layers one thing to note that this actually gave me some trouble because it means we understand how this works but if you disable some of these layers in the device it's this is going to be just fine these coins runs is fine no crushing but if you actually disable some of these layers in the instance if you do this now this code will crash because it can't find these ones in the instance so basically what you will need to remember is all the layers that you plan to use in your application they will need to be in the instance and if I run this now it's going to crash so yeah create device failed because it couldn't find these layers in the instance that's all about this let's create the in its and debug function okay so what we are going to put into this function would be VK create debug report call back extension or eh team there's a slight problem though and if I just try this and try to run this the visual studio says that unresolved external symbol this means that this function here this VK create a deepak report callback is not exposed by the vulcan loader by default the vulcan specification does not say that the loader needs to load any function at all or expose any of the function at all and the luna g's loader only exposes the core vulcan functions as well as as the WSI extension functions this function belongs to debark reports extension and that extension is not available by default so I'm just gonna come comment this out come and see what we need is an instance extension I'm going to push back a name actually it's a macro this is called BK EXT deepak report extension name now this introduces these extensions Valken and we need this to be able to create the Deepak report called back the next step is actually going to create a place for the function pointer so type in pfn underscore VK create debug report call back ext this is a function type I'm gonna call this function exactly this but just put an F in front of it just to tell that it's fetched pointer or fetch function and that it has a null pointer by default I'm gonna copy this and replace all the creates in this with destroy we need two functions we need to fetch two functions so how to get this pointer to serve you can just ask walking about this we're going to use a function called VK get instance proc add or I guess it's a procedure procedure and dress this takes the instance and it takes the functions name so I want to use this function you can copy and paste it here and it returns this function pointer and then I'm gonna do just the C typecast because this function returns PFN underscore VK void function so doing a cast here and now it's all as it should be I'm gonna copy this and paste it here and replace the create with destroy that should care ask the function pointers we need and I also want to check that we actually cut the pointers so doing it right here if either one of these is null pointer as said in here which is can assert and exits and after this we can just use these functions this function takes an instance as well as Deepak report called back create info ext and that's a structure callback allocation callbacks all pointer here this is a bit funny one it returns us a handle I'm actually going to store this handle and the renderer class and I'm gonna call it Deepak report and it's a handle so I'm just gonna put it to null give it to this function here now this leaves us with VK Deepak report called by creating for ext structure so let's create that and I'm gonna simplify the name a little bit and just call this debug call back create info and I'm going to give this pointer to this function here now in this structure this might be familiar s type first which is a VK structure type debark report creating for ext also flags we need to set the flags and the PFN called back which is our callback to the which is our pointer to the callback function P next and user dates are we're not gonna touch them just can I set the pfn call back to nothing yet we need to create that function the last thing is flags there's quite a few flags for this actually I'm gonna enable it all the flags see the flags here tell which kinds of reports we want to actually call the callback for I'm just gonna copy all of these and and you have these happy feel flag so you can enable them all in this in one go okay so let's create our callback I'm actually going to create the callback between the DNA devising before setup debug how you do this is basically BK API attribute then you need to put BK all 32 BK API call here okay name it whatever you want to I'm just gonna name it as a walk-on debug callback this function takes quite a few parameters and I'm gonna do a multi-line so the first one is a VK d bug report flags ext I'm going to name this as a MSG Flags the second parameter is a VK d park report object type gonna name this as object type the next is you int 64 T this will be source object size T location in 32 not you in span yeah int 32 T this will be a message code and then there's a couple of contours so see type strings this first one will be a layer prefix the second one built be another contour and this will be the actual message the last one is a void pointer to user data so what do all of these mean the message flags actually I'm just going to rename it as flags the flags all the Deepak report flags this will be what kind of error or report we are handling here it could be like warning or error each one of these technically these flags don't allow couple of these to be overlapping and I'm not sure if this is ever the case but so far it doesn't seem to be so flags reports only one as far as I know object type now this is not something I was expecting because this is the type of object that caused the error not win which object the error was happening so to say this simply if you create the instance then create device and then you create like command pool and after that you destroy the device and then the instance when you destroy that device it's going to report it because that's going to cause some memory leaks and you don't want that this callback is going to fire and this object type will be let's see here the command Paul VK Deepak report object type command Paul ext because the command pool was the thing that caused the error in the first place the source object is a UN 64 and this is basically the pointer to that object basically you could recreate the structure here if you wanted with these two size T location now this is a bit funny one I have no idea what it does but I guess it's a source code line where the error happened in the layer itself but I cannot be sure about this so don't take my word on it message code this is a bit hazy to me as well it seems to be related to the flags like the debug and info flags will both return message code zero while the error returns message code four so it could be like how important this callback or this call to this callback is but yeah I need to study this a bit more I unfortunately I didn't find any explanations for these ones anywhere since this is an extension you won't be finding it in the Vulcan Plus WSI extension specification this is different from the core and this is different from the WSI extension the next one is layer prefix or prefix however you want to say that with layer prefix tells us which layer call this callback the message is actually really easy to read it's a human readable string and user data I'm not going to even touch now this function can return true or false and based on which one you return that defines how the layers will act on the error or this callback if you return true in that case this layer is going to try and bail out from the command that UK Balkan so the command itself does not reach welcome Vulcan core or even the second layer if you return false in that case it will go all the way to walk-in core I highly recommend that you return false always unless you really need to try return true because when you return false that basically guarantees that the program in debugging works exactly the same with its faults and errors as would the final product so returning false let's try this and actually just print out the message unless you what happens nothing because I forgot to give the pointer to this function in here also I forgot all of other things first of all let's tidy up a little bit we've got quite a few things in here actually let's create the our tea in it Deepak function and in this function it's kind of easy we'll just call the fvk destroy depart report call back well this function takes is an instance again it takes the Deepak reports handled that we created on the create account report call back so this one here as well as the allocation callbacks I'm just going to put it to null pointer again in these tutorials you can expect that the allocation callbacks will always be a null pointer and I'm going to set the default report in all pointer too just in case now in the renderer constructor and destructor I'm gonna in it the debug and in the destructor I'm going to T in it the D part right before I D in it or destroy the instance okay let's try again that was a lot of stuff I saw that but went too fast so let's put a breakpoint to the destructor the end of it there okay so we got a bunch of things in here added callback six callbacks actually we added six callbacks because we added these callbacks to each layer and this layer support this extension the default report extension if the layer does not support default report extension in that case it will not add the callback and let's actually refine our callback a little bit so what I want to know in here is what kind of report this is is it an error or warning or performance warning or what is it if flags has a bit and let's see the bits actually information bit in that case I'm gonna print out info and leave it at start and then I'm just gonna copy this and add the rest as well as pulling the right strings into these fields or sea out warning info performance error and debug and doing some more refining here and after this I want to know which layer this report is coming from let's put an ad and then the layer prefix and close this and then the message itself okay let's see what happens now okay Deepak Deepak report Deepak report in this case is the extension the next one info at obg track which is a layer and then there's the lower debug information from the loader it just tells us that it's loading all these and these extensions and layers object rack men object track and all that so that's fine actually I want to do one more thing in here and that's because II can't Deepak that creates instance function to enable that you need to do one final step and to do that we are going to move this VK Deepak report called back create info into our class renderer class and then we are going to move all of this into our set up just putting it to the first one here our first thing in here and now how this enables us to debug the create instance function is by going into this instance creates info structure and actually giving the P next pointer we're going to give it a pointer to debug called back create info so this seems like magic all right but it works so running this again there's a lot more information about the lower right now and now our program will be debarked basically from all the way from instance creation to its destruction I actually want to add one more thing to do to the reporting callback but this is kind of a Windows only thing if defined win32 include Windows that dot H and indigent epoch in the callback function I'm going to move these C out to strings or STD o string string and I'm conscious pile everything up to this one stream and then print the whole stream after this if you have Windows operating system so if defined we know 32 which is gonna call the message box and let's only show this if there's an error actual error so just gonna copy not have one but this one here oh there we go now it should show us a message box whenever there's an error let's actually create one I'm gonna go back to the main dot h CP P and don't worry about this too much yet it's coming in the future tutorials but I'm just gonna create an error by making a command pool and not destroying it looking basically what were you doing now we're initializing the renderer then we are going to create a command pool here then we're gonna return which destroys the renderer he also risked destroys the device that leaves us a hanging command pool handle so memory is actually not freed now if we've run this yeah we do actually get an error message here which says that error add object track object error VK Deepak report object type command poly ext object of this address has not been destroyed so this works is perfectly and that's basically all I have to show to you for this tutorial I hoped you liked it and we'll see again

Channel: Niko Kauppi

Views: 23,477

Keywords: vulkan, api, tutorial, debug, debugging, specification, graphics, programming, gpu, graphics card, c++, cpp, code, coding, advanced, close to metal, glnext

Id: raXIWyWBv2I

Length: 47min 13sec (2833 seconds)

Published: Sat Mar 12 2016