{"id":13731939,"url":"https://github.com/dfranx/ShaderDebugger","last_synced_at":"2025-05-08T06:30:41.932Z","repository":{"id":65390036,"uuid":"211347906","full_name":"dfranx/ShaderDebugger","owner":"dfranx","description":"[DEPRECATED] C++ library for debugging HLSL \u0026 GLSL shaders","archived":false,"fork":false,"pushed_at":"2020-04-07T10:47:09.000Z","size":455,"stargazers_count":327,"open_issues_count":0,"forks_count":21,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-08-04T02:10:37.749Z","etag":null,"topics":["compiler","debugger","glsl","hlsl","shader-editor"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dfranx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"patreon":"dfranx","custom":"https://paypal.me/dfranx"}},"created_at":"2019-09-27T15:20:51.000Z","updated_at":"2024-08-02T08:09:58.000Z","dependencies_parsed_at":"2023-02-24T19:00:23.011Z","dependency_job_id":null,"html_url":"https://github.com/dfranx/ShaderDebugger","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfranx%2FShaderDebugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfranx%2FShaderDebugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfranx%2FShaderDebugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfranx%2FShaderDebugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dfranx","download_url":"https://codeload.github.com/dfranx/ShaderDebugger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224707552,"owners_count":17356352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","debugger","glsl","hlsl","shader-editor"],"created_at":"2024-08-03T02:01:41.978Z","updated_at":"2024-11-14T23:30:34.632Z","avatar_url":"https://github.com/dfranx.png","language":"C++","readme":"# ShaderDebugger\n\n**This project is deprecated**. Check [SPIRV-VM](https://www.github.com/dfranx/SPIRV-VM) instead.\n\nShaderDebugger is a cross platform C++ library that can be used to debug GLSL and HLSL shaders.\nIt has plenty of cool features: conditional breakpoints, step-by-step debugging, executing expressions on the fly, get variable values, etc...\nWe will describe each of those in more details later in this README file.\n\nShaderDebugger let's you see what actually happens in your shaders without having to use #ifs or some other tricks.\n\nIf you don't care about all of this and just want to see ShaderDebugger in action, check [SDBG](https://github.com/dfranx/sdbg) - a CLI shader debugger.\n\n## How and why?\nThis library parses shaders into AST using [glsl-parser](https://github.com/dfranx/glsl-parser) \u0026 [hlslparser](https://github.com/dfranx/hlslparser).\nThe AST is then traversed to generate bytecode using the [aGen](https://github.com/dfranx/aGen) library.\nThe generated bytecode can then be executed using [BlueVM](https://github.com/dfranx/BlueVM).\n\nShaderDebugger was made to add debugging feature to [SHADERed](https://github.com/dfranx/SHADERed)\nbut it is MIT licensed which means that anyone can use, distribute, modify it, etc...\n\nI encourage you to integrate it into your own project! Consider sharing your (or someone's) ShaderDebugger projects here: [link](https://github.com/dfranx/ShaderDebugger/issues/2)\n\n## Integrating\nIf you want to add ShaderDebugger to your project, just add_subdirectory ShaderDebugger:\n\nFor example, first clone ShaderDebugger:\n```bash\ngit clone https://github.com/dfranx/ShaderDebugger.git\ncd ShaderDebugger\ngit submodule init\ngit submodule update\n```\n\nYou can then add ShaderDebugger to your project:\n```cmake\nadd_subdirectory(./path/to/your/ShaderDebugger)\n```\n\nAfter you've added it to your project, you can link it:\n```cmake\ntarget_link_libraries(your_project ShaderDebugger)\n```\n\nShaderDebugger has only one dependency: **glm**.\n\n## Example\n```c++\nstd::string src = \"... your shader code ...\";\n\nsd::ShaderDebugger dbg;\ndbg.SetSource\u003csd::GLSLCompiler\u003e(sd::ShaderType::Pixel, src, \"main\", NULL, sd::GLSL::Library());\n// or dbg.SetSource\u003csd::HLSLCompiler\u003e(sd::ShaderType::Pixel, src, \"main\", NULL, sd::HLSL::Library());\n\ndbg.SetGlobalValue(\"iFactor\", 0.7f);\ndbg.SetGlobalValue(\"iColor\", \"vec3\", glm::vec4(0.5f, 0.6f, 0.7f, 0.0f));\n\nbv_variable ret = dbg.Execute(); // execute the entry function\n\nglm::vec3 outColor = sd::AsVector\u003c3, float\u003e(*dbg.GetGlobalValue(\"outColor\"));\nprintf(\"outColor = vec3(%.2f, %.2f, %.2f);\\n\", outColor.x, outColor.y, outColor.z);\n\nbv_variable_deinitialize(\u0026ret);\n```\n\nOr you can execute code line by line:\n```c++\nwhile (vs.Step()) {\n    // get various info: GetCurrentFunction, GetFunctionStack, GetGlobalValue, GetLocalValue, etc...\n}\n```\n\nYou can also execute expressions using the `ShaderDebugger::Immediate`:\n```c++\nbv_variable result = dbg.Immediate(\"sin(a * 2.0f) + texture(tex, uv).x\");\n// result contains the result of the expression\nbv_variable_deinitialize(\u0026result);\n```\n\n## Screenshots\n[SDBG](https://github.com/dfranx/sdbg) in action:\n\u003cp align=\"center\"\u003e\n    \u003cimg width=\"500\" src=\"https://raw.githubusercontent.com/dfranx/sdbg/master/misc/screen1.gif\"\u003e\n\u003c/p\u003e\n\n## Documentation\nI am working on a website which will host documentation for ShaderDebugger and SHADERed.\nBut until then, function descriptions will be located here:\n#### ShaderDebugger::SetSource\\\u003cCompiler\\\u003e(stage, source, entry, args, library)\nCompiler is a class type which is used to compile the `source` into the bytecode.\nCurrently only pixel and vertex stages are supported, but more might be added in future.\n`library` is a instance of `bv_library`. It contains all the object definitions (vec3, mat3, ...)\nand all the function implementations (sin, cos, ...).\n`sd::HLSLCompiler` and `sd::HLSL::Library()` are used for HLSL shaders, while \n`sd::GLSLCompiler` and `sd::GLSL::Library()` are used for GLSL shaders.\n`SetSource` returns false when an error occurs. To get the error message use `GetLastError()`.\nIf an error occurs, please refrain from calling any other ShaderDebugger methods as they will cause a crash.\n\n#### ShaderDebugger::Step()\nStep 1 line.\n\n#### ShaderDebugger::StepOver()\nStep 1 line but don't enter the functions that are used on that line.\n\n#### ShaderDebugger::StepOut()\nExecute the code until we leave current function.\n\n#### ShaderDebugger::Immediate(expression)\nExecute an expression and return it's value. Example: `bv_variable var = dbg.Immediate(\"acc + sin(tex.Sample(smp, uv).x)\");`\n\n#### ShaderDebugger::AddBreakpoint(line)\nAdd a basic breakpoint on the provided line.\n\n#### ShaderDebugger::AddConditionalBreakpoint(line, condition)\nAdd a conditional breakpoint on the provided line. Example: `dbg.AddConditionalBreakpoint(17, \"i \u003e 10\")`\n\n#### ShaderDebugger::Execute(function, args)\nThis method runs some function defined in the shader code.\nExample: `dbg.Execute(\"someRandomFunction\", NULL)`.\nThis way you can test some other functions manually without having to run the whole main()/entry function.\n\nCall `Execute()` with no arguments to execute the entry function. Even though it is possible to render the whole scene using ShaderDebugger,\nI suggest that you do not do that. It would take ages. ShaderDebugger/BlueVM need to improve quite a lot for this to be plausible.\n\n#### ShaderDebugger::GetCurrentFunction()\nReturns the name of the function which is currently being executed.\n\n#### ShaderDebugger::GetFunctionStack()\nAs the name suggest, this method returns the function stack (list of functions).\n\n#### ShaderDebugger::GetCurrentFunctionLocals()\nGet list of all local variable names used in the current function\n\n#### ShaderDebugger::GetLocalValue(varname)\nGet a value of the local variable that has the same name as the provided one.\nExample: `bv_variable* var = dbg.GetLocalValue(\"tempColor\")`.\nIf a variable with such name doesn't exist, GetLocalValue will return nullptr.\n\n#### ShaderDebugger::GetCurrentLine()\nGet the number of line on which the `internal stepper` is located on.\n\n#### ShaderDebugger::Jump(line)\nMake the `internal stepper` jump to the provided line.\n\n#### ShaderDebugger::Continue()\nRun the code until we hit some breakpoint or exit the entry function.\nIf ShaderDebugger hit a breakpoint when stepping through the code, it will automatically stop and Continue() will return `true`.\nOtherwise, it will execute whole code and return `false`.\n\n#### ShaderDebugger::SetSemanticValue(semantic, value)\nBind a value to a certain semantic string. Example: `dbg.SetSemanticValue(\"SV_Depth\", bv_variable_create_float(0.1f));`\n\n#### ShaderDebugger::AddGlobal(name)\nAdd a global variable definition. Example: `dbg.AddGlobal(\"gl_FragCoord\");`\n\n#### ShaderDebugger::SetGlobalValue(name, value)\nChange global variable's value. Example: `dbg.SetGlobalValue(\"gl_FragCoord\", \"vec4\", glm::vec4(100, 100, 0, 0));`\n\n#### ShaderDebugger::IsDiscarded()\nCheck if the `discard;` command was called.\n\n#### ShaderDebugger::GetCompiler()\nGet the pointer to the compiler that was used to compile the shader.\n\n#### Compiler::GetGlobals()\nGet the list of all global variables.\n\n#### Compiler::GetStructures()\nGet the list of all user defined structures (their definition information - for example: members).\n\n#### Compiler::GetFunctions()\nGet the list of all user defined functions.\n\n#### Compiler::GetLocals(func)\nGet the list of all local variables inside of a function.\n\n#### Compiler::GetLocalType(func, varname)\nGet the type of the local variable in some function.\n\n#### Other functions\nThere are plenty of other functions but I encourage you to download ShaderDebugger and explore them yourself!\n\n## Partners / Sponsors\n...\n\nContact: **dfranx00 at gmail dot com**\n\n## Supporters\n**Silver supporter(s):**\n[Hugo Locurcio](https://github.com/Calinou)\n\n\n## Support\nSupport the development of this project on Patreon: [\u003cimg width=\"120\" src=\"https://c5.patreon.com/external/logo/become_a_patron_button@2x.png\"\u003e](https://www.patreon.com/dfranx)\n\nYou can support the development of this project via **PayPal**: [\u003cimg src=\"https://www.paypalobjects.com/webstatic/en_US/i/buttons/pp-acceptance-medium.png\" alt=\"Buy now with PayPal\" /\u003e](https://paypal.me/dfranx) \n\nMy e-mail address for businesses (or if you just want to contact me):\n**dfranx00 at gmail dot com**\n\n## TODO\nHere is the list of features/bugfixes that I need to do:\n\n### GLSL\n- interface blocks\n- local \u0026 structure member arrays\n- fix ternary statement parsing\n\n### HLSL\n- classes / interfaces\n- namespaces\n- switch statement\n- matrix\u003cT, X, Y\u003e, vector\u003cT, X\u003e\n- initializer lists\n\n### Both\n- cubemaps\n- some function implementations are missing (check HLSLLibrary.cpp / GLSLLibrary.cpp)\n- expand all HLSL library functions to support matrices too (example: abs(some_matrix))\n- fix matrixes, these don't work:\n  - mat4 m; m[0].x = 1.0f;\n  - mat4 m[4]; m[0][0][0];\n\n## LICENSE\nShaderDebugger is licensed under MIT license. See [LICENSE](./LICENSE) for more details.\n","funding_links":["https://patreon.com/dfranx","https://paypal.me/dfranx","https://www.patreon.com/dfranx"],"categories":["Graphics"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfranx%2FShaderDebugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdfranx%2FShaderDebugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfranx%2FShaderDebugger/lists"}