Skip to content

Commit cb159ad

Browse files
christophe-lunargchristophe-lunarg
committed
vkconfig: Add per-setting documentation
1 parent 876fe5b commit cb159ad

7 files changed

Lines changed: 179 additions & 31 deletions

File tree

‎vkconfig_core/header.cpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@ const char* GetToken(SettingView state) {
5353
void LoadMetaHeader(Header& header, const QJsonObject& json_object) {
5454
header.label = ReadStringValue(json_object, "label");
5555
header.description = ReadStringValue(json_object, "description");
56+
if (json_object.value("detailed") != QJsonValue::Undefined) {
57+
header.detailed = ReadStringValue(json_object, "detailed");
58+
}
5659
if (json_object.value("url") != QJsonValue::Undefined) {
5760
header.url = Path(ReadStringValue(json_object, "url"), false);
5861
}

‎vkconfig_core/header.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ struct Header {
4646

4747
std::string label;
4848
std::string description;
49+
std::string detailed;
4950
Path url;
5051
StatusType status;
5152
std::string deprecated_by_key;

‎vkconfig_core/layers/layers_schema.json‎

Lines changed: 55 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,11 @@
280280
"type": "string"
281281
},
282282
"description": {
283+
"description": "The brief description of the setting",
284+
"type": "string"
285+
},
286+
"detailed": {
287+
"description": "The detailed description of the setting",
283288
"type": "string"
284289
},
285290
"url": {
@@ -439,7 +444,11 @@
439444
"type": "string"
440445
},
441446
"description": {
442-
"description": "The description of the setting",
447+
"description": "The brief description of the setting",
448+
"type": "string"
449+
},
450+
"detailed": {
451+
"description": "The detailed description of the setting",
443452
"type": "string"
444453
},
445454
"url": {
@@ -602,7 +611,11 @@
602611
"type": "string"
603612
},
604613
"description": {
605-
"description": "The description of the setting",
614+
"description": "The brief description of the setting",
615+
"type": "string"
616+
},
617+
"detailed": {
618+
"description": "The detailed description of the setting",
606619
"type": "string"
607620
},
608621
"url": {
@@ -699,7 +712,11 @@
699712
"type": "string"
700713
},
701714
"description": {
702-
"description": "The description of the setting",
715+
"description": "The brief description of the setting",
716+
"type": "string"
717+
},
718+
"detailed": {
719+
"description": "The detailed description of the setting",
703720
"type": "string"
704721
},
705722
"url": {
@@ -809,7 +826,11 @@
809826
"type": "string"
810827
},
811828
"description": {
812-
"description": "The description of the setting",
829+
"description": "The brief description of the setting",
830+
"type": "string"
831+
},
832+
"detailed": {
833+
"description": "The detailed description of the setting",
813834
"type": "string"
814835
},
815836
"url": {
@@ -916,7 +937,11 @@
916937
"type": "string"
917938
},
918939
"description": {
919-
"description": "The description of the setting",
940+
"description": "The brief description of the setting",
941+
"type": "string"
942+
},
943+
"detailed": {
944+
"description": "The detailed description of the setting",
920945
"type": "string"
921946
},
922947
"url": {
@@ -1020,7 +1045,11 @@
10201045
"type": "string"
10211046
},
10221047
"description": {
1023-
"description": "The description of the setting",
1048+
"description": "The brief description of the setting",
1049+
"type": "string"
1050+
},
1051+
"detailed": {
1052+
"description": "The detailed description of the setting",
10241053
"type": "string"
10251054
},
10261055
"url": {
@@ -1141,7 +1170,11 @@
11411170
"type": "string"
11421171
},
11431172
"description": {
1144-
"description": "The description of the setting",
1173+
"description": "The brief description of the setting",
1174+
"type": "string"
1175+
},
1176+
"detailed": {
1177+
"description": "The detailed description of the setting",
11451178
"type": "string"
11461179
},
11471180
"url": {
@@ -1242,7 +1275,11 @@
12421275
"type": "string"
12431276
},
12441277
"description": {
1245-
"description": "The description of the setting",
1278+
"description": "The brief description of the setting",
1279+
"type": "string"
1280+
},
1281+
"detailed": {
1282+
"description": "The detailed description of the setting",
12461283
"type": "string"
12471284
},
12481285
"url": {
@@ -1445,7 +1482,11 @@
14451482
"type": "string"
14461483
},
14471484
"description": {
1448-
"description": "The description of the setting",
1485+
"description": "The brief description of the setting",
1486+
"type": "string"
1487+
},
1488+
"detailed": {
1489+
"description": "The detailed description of the setting",
14491490
"type": "string"
14501491
},
14511492
"url": {
@@ -1568,7 +1609,11 @@
15681609
"type": "string"
15691610
},
15701611
"description": {
1571-
"description": "The description of the setting",
1612+
"description": "The brief description of the setting",
1613+
"type": "string"
1614+
},
1615+
"detailed": {
1616+
"description": "The detailed description of the setting",
15721617
"type": "string"
15731618
},
15741619
"url": {

‎vkconfig_core/path.cpp‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,17 @@ const char* Path::Separator() {
7979
return native_separator;
8080
}
8181

82+
std::string ConvertStandardSeparators(const std::string& path) {
83+
if (VKC_ENV == VKC_ENV_WIN32) {
84+
const char* std_separator = "/";
85+
const char* alien_separator = VKC_ENV == VKC_ENV_WIN32 ? "\\" : "/";
86+
87+
return ConvertSeparators(path, std_separator, alien_separator);
88+
} else {
89+
return path;
90+
}
91+
}
92+
8293
std::string ConvertNativeSeparators(const std::string& path) {
8394
const char* native_separator = Path::Separator();
8495
const char* alien_separator = VKC_ENV != VKC_ENV_WIN32 ? "\\" : "/";

‎vkconfig_core/path.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ class Path {
8383
std::string AbsolutePath(Path::Builtin path, bool native_separator = true);
8484
std::string RelativePath(Path::Builtin path);
8585

86+
std::string ConvertStandardSeparators(const std::string& path);
8687
std::string ConvertNativeSeparators(const std::string& path);
8788
std::string TrimEndSeparator(const std::string& path);
8889

‎vkconfig_gui/CHANGELOG.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,11 @@
55
- Add support for layer-defined messages
66

77
### Improvements:
8-
- Add optional information about which setting replaced a deprecated setting
9-
- Display deprecated setting information in generated layer documentation
8+
- Improved layer settings documentation
9+
- Add layer setting context menu to access setting documentation
10+
- Add detailed description layer setting field
11+
- Add display of deprecated setting information in generated layer documentation
12+
- Add optional information about which setting replaced a deprecated setting
1013

1114
## Vulkan Configurator 3.2.0 - May 2025
1215
[Vulkan SDK 1.4.313.0](https://github.com/LunarG/VulkanTools/tree/vulkan-sdk-1.4.313)

‎vkconfig_gui/tab_configurations.cpp‎

Lines changed: 103 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
#include "mainwindow.h"
2424
#include "widget_resize_button.h"
2525
#include "style.h"
26+
#include "item_tree.h"
2627

2728
#include "../vkconfig_core/configurator.h"
2829
#include "../vkconfig_core/doc.h"
@@ -34,25 +35,33 @@
3435
#include <QDesktopServices>
3536
#include <QMessageBox>
3637

37-
static std::string BuildPropertiesLog(const Layer &layer) {
38-
std::string description;
39-
if (!layer.description.empty()) {
40-
description += layer.description + "\n";
41-
}
42-
description += "API Version: " + layer.api_version.str() + " - Implementation Version: " + layer.implementation_version + "\n";
43-
if (layer.platforms != 0) {
44-
description += "Supported Platforms: ";
38+
static std::string BuildPlatformsLog(int platforms) {
39+
std::string log;
4540

46-
const std::vector<std::string> &platforms = GetPlatformTokens(layer.platforms);
47-
for (std::size_t i = 0, n = platforms.size(); i < n; ++i) {
48-
description += platforms[i];
41+
if (platforms != 0) {
42+
log += "Platforms: ";
43+
44+
const std::vector<std::string> &list = GetPlatformTokens(platforms);
45+
for (std::size_t i = 0, n = list.size(); i < n; ++i) {
46+
log += list[i];
4947
if (i < n - 1) {
50-
description += ", ";
48+
log += ", ";
5149
}
5250
}
5351

54-
description += "\n";
52+
log += "\n";
53+
}
54+
55+
return log;
56+
}
57+
58+
static std::string BuildPropertiesLog(const Layer &layer) {
59+
std::string description;
60+
if (!layer.description.empty()) {
61+
description += layer.description + "\n";
5562
}
63+
description += "API Version: " + layer.api_version.str() + " - Implementation Version: " + layer.implementation_version + "\n";
64+
description += ::BuildPlatformsLog(layer.platforms);
5665

5766
description += "\n";
5867
description += layer.manifest_path.AbsolutePath() + "\n";
@@ -457,10 +466,10 @@ bool TabConfigurations::EventFilter(QObject *target, QEvent *event) {
457466

458467
if (configurator.GetExecutableScope() == EXECUTABLE_NONE || !ui->configurations_list->isEnabled()) {
459468
return true;
460-
} else if (target == ui->configurations_list) {
469+
} else if (target == this->ui->configurations_list) {
461470
QContextMenuEvent *right_click = dynamic_cast<QContextMenuEvent *>(event);
462471
if (right_click) {
463-
ListItem *item = static_cast<ListItem *>(ui->configurations_list->itemAt(right_click->pos()));
472+
ListItem *item = static_cast<ListItem *>(this->ui->configurations_list->itemAt(right_click->pos()));
464473

465474
std::string name;
466475

@@ -539,18 +548,18 @@ bool TabConfigurations::EventFilter(QObject *target, QEvent *event) {
539548
this->OnContextMenuExportSettingsClicked(item);
540549
}
541550
}
542-
} else if (target == ui->configurations_layers_list) {
551+
} else if (target == this->ui->configurations_layers_list) {
543552
QContextMenuEvent *right_click = dynamic_cast<QContextMenuEvent *>(event);
544553
if (right_click) {
545-
ListItem *item = static_cast<ListItem *>(ui->configurations_layers_list->itemAt(right_click->pos()));
554+
ListItem *item = static_cast<ListItem *>(this->ui->configurations_layers_list->itemAt(right_click->pos()));
546555

547556
if (item != nullptr) {
548557
const Configuration *configuration = configurator.GetActiveConfiguration();
549558
const Parameter *parameter = configuration->Find(item->key);
550559

551560
const Layer *layer = configurator.layers.FindFromManifest(parameter->manifest);
552561

553-
QMenu menu(ui->configurations_layers_list);
562+
QMenu menu(this->ui->configurations_layers_list);
554563

555564
QAction *action_description = new QAction("Open the Layer Description...", nullptr);
556565
action_description->setEnabled(layer != nullptr);
@@ -597,14 +606,89 @@ bool TabConfigurations::EventFilter(QObject *target, QEvent *event) {
597606
} else if (action == export_html_action) {
598607
const std::string path = format("%s/%s.html", AbsolutePath(Path::APPDATA).c_str(), layer->key.c_str());
599608
ExportHtmlDoc(*layer, path);
600-
QDesktopServices::openUrl(QUrl(("file:///" + path).c_str()));
609+
std::string url = "file:///" + path;
610+
QDesktopServices::openUrl(QUrl(url.c_str()));
601611
} else if (action == export_markdown_action) {
602612
const std::string path = format("%s/%s.md", AbsolutePath(Path::APPDATA).c_str(), layer->key.c_str());
603613
ExportMarkdownDoc(*layer, path);
604614
QDesktopServices::openUrl(QUrl(("file:///" + path).c_str()));
605615
}
606616
}
607617
}
618+
} else if (target == this->ui->configurations_settings) {
619+
QContextMenuEvent *right_click = dynamic_cast<QContextMenuEvent *>(event);
620+
if (right_click) {
621+
TreeItem *item = static_cast<TreeItem *>(this->ui->configurations_settings->itemAt(right_click->pos()));
622+
623+
const Configuration *configuration = configurator.GetActiveConfiguration();
624+
const Parameter *parameter = configuration->GetActiveParameter();
625+
626+
const Layer *layer = configurator.layers.FindFromManifest(parameter->manifest);
627+
628+
if (item != nullptr) {
629+
QMenu menu(this->ui->configurations_settings);
630+
631+
QAction *action_description = new QAction("Open the brief Setting Description...", nullptr);
632+
action_description->setEnabled(layer != nullptr);
633+
menu.addAction(action_description);
634+
635+
QAction *export_html_action = new QAction("Open the detailed Setting HTML Documentation...", nullptr);
636+
export_html_action->setEnabled(layer != nullptr);
637+
menu.addAction(export_html_action);
638+
639+
QPoint point(right_click->globalX(), right_click->globalY());
640+
QAction *action = menu.exec(point);
641+
642+
if (action == action_description) {
643+
const SettingMeta *setting = ::FindSetting(layer->settings, item->key.c_str());
644+
assert(layer != nullptr);
645+
646+
std::string title = format("%s (%s)", setting->label.c_str(), setting->key.c_str());
647+
if (setting->status != STATUS_STABLE) {
648+
title += format(" (%s)", ::GetToken(setting->status));
649+
}
650+
651+
std::string text = setting->description;
652+
text += "\n\n";
653+
if (!setting->detailed.empty()) {
654+
text += setting->detailed;
655+
text += "\n\n";
656+
}
657+
658+
text += "VK_EXT_layer_settings name:\n";
659+
text += format(" %s\n", setting->key.c_str());
660+
text += "vk_layer_settings.txt variable:\n";
661+
text += format(" %s\n", (GetLayerSettingPrefix(layer->key) + setting->key).c_str());
662+
text += "Environment variables:\n";
663+
std::vector<std::string> envs = BuildEnvVariablesList(layer->key.c_str(), setting->key.c_str());
664+
if (!setting->env.empty()) {
665+
envs.push_back(setting->env);
666+
}
667+
for (std::size_t i = 0, n = envs.size(); i < n; ++i) {
668+
text += format(" %s\n", envs[i].c_str());
669+
}
670+
text += "\n";
671+
672+
text += format("Type: %s\n", ::GetToken(setting->type));
673+
text += format("Default Value: %s\n", setting->Export(EXPORT_MODE_DOC).c_str());
674+
text += ::BuildPlatformsLog(setting->platform_flags);
675+
676+
QMessageBox alert;
677+
alert.setWindowTitle(title.c_str());
678+
alert.setText(text.c_str());
679+
alert.setStandardButtons(QMessageBox::Ok);
680+
alert.setDefaultButton(QMessageBox::Ok);
681+
alert.setIcon(QMessageBox::Information);
682+
alert.exec();
683+
} else if (action == export_html_action) {
684+
const std::string path = format("%s/%s.html", AbsolutePath(Path::APPDATA).c_str(), layer->key.c_str());
685+
ExportHtmlDoc(*layer, path);
686+
687+
std::string url = ConvertStandardSeparators(format("file:///%s#%s-detailed", path.c_str(), item->key.c_str()));
688+
QDesktopServices::openUrl(QUrl(url.c_str()));
689+
}
690+
}
691+
}
608692
}
609693

610694
// Pass it on

0 commit comments

Comments
 (0)