Documentation

[jpbruyere]

Documentation

[Joaopmoliveira]

So i do have those directories and i am currently trying the solution with the env variables but the solution you point to would be the best, because then you have a self contained piece of code which does not require "complex" settings by the end user.

[jpbruyere]

For sure it would be helpful. Maybe the most important point to keep in mind first on the development is that there are two main branches:
The master branch, which use vulkan push constants to set solid colors. When testing performances with other libraries, I had to concede that it was impossible to reach the highest perf if not enough vertices are outputed by draw call. So I start exploring the 'vertex color' solution (newvertex branche). The master has been more tested and is where I try to implement new functionalities (I'm working on dashes). The newvertex branch will be merge into master but first I have to handle more tests on it.
That being said, The api documentation try to follow the Cairo api (www.cairographics.org), I try to make doc comments to autogenerate the api docs.
For open source programs, it is important to split user docs from development docs. The internals of the library is maybe what you're interested in, I'll try to make a resume on the wiki with an overall drawing of the internals.
The user docs will be automated for the api (with doxygen). If you feel confident with that part, feel free to implement the best choices for auto-generation.
Other doc tasks:

• VKVG has not yet it's github.io site, it would also be great to work on that for presenting and storing docs.
• README could also be improved.
• compilation instructions, debian package gen with 'cpack'.
• tutorials, it would be great to have those made by someone discovering the lib.
  Until now I've work alone on vkvg, feel free to help opening that lib to the open source community.
• 'vgperf' repo is where I make skia, cairo, vkvg perf tests
• 'vkvg.net' is a c# wrapper

Thanks in advance for any help, even little contributions are welcome to make this project live.

jp

[jpbruyere]

Also I make no publicity for now, but feel free to make vkvg known to the open source community.

[Joaopmoliveira]

So first i will try to sift through the code base. I will also try to write some Markdown documents for myself first, to help me understand the inner workings, and then you can see what is salvageable or not to be shown to the user of the library.

[Joaopmoliveira]

The tutorials are also something i can try to work on, since i will be actually discovering how everything comes together!

[jpbruyere]

Ok, I'm there for any questions, don't hesitate.

[jpbruyere]

I've put a brief explanation in the wiki with drawings of the path array which is quiet tricky.

[Joaopmoliveira]

Is it ok if i write the tutorials for Visual Studio and then we can try to translate them into other platforms?

[jpbruyere]

Yes, feel free to do the best for you first.

[Joaopmoliveira]

Question 1: I understand that the vkh library is an independent project from the vkvg library but my question is: should the tutorials use the functionality provided by vkh or should they deal with the Vulkan API directly? I do understand that some basic structs from from vkvg are built upon vkh.

[jpbruyere]

If you feel confident with vulkan rendering loops, you may provide your own code or point to official samples of Khronos or lunarg, vkh is not documented, so maybe it's better to have some details of the init and the loop explained without referring too much to vkh, you may even copy code from vkh for your samples without linking to it. vkh is for internal simplification, if we use it for the samples, it should be documented and reviewed.

[Joaopmoliveira]

So i am trying to build the examples and to do so i am trying to build upon the vulkan tutorial which seems like one of the most used tutorials for the API (https://vulkan-tutorial.com/Drawing_a_triangle/Setup/Logical_device_and_queues) and i am facing a problem. The function vkvg_device_create requires a queue family index. Is there some specific family queue which is required by the library?

[jpbruyere]

The provided queue must have the GRAPHIC flag set. Index is usually 0. It's the queue index inside a single family. Usually the first is ok. The queue creation structure has it's default value to 0 in the triangle sample.

[Joaopmoliveira]

Tutorial for windows on Visual Studio:

1. Make sure that Git is installed on your machine by typing on the command line
   git --version

If the output of such command is:
git version 2.19.1.windows.1

Then you have git installed on your machine. If an error is given, then install git on your machine.

2. To install all the necessary libraries we first need to install the vcpkg packagde manager (the process can be done manually but it is easier this way) which allows one to link projects with a large array of libraries already developed in C\C++. To instalation is trivial, you just go to the command line, and write
   git clone https://github.com/Microsoft/vcpkg.git
   cd vcpkg
   .\bootstrap-vcpkg.bat

3. Now we have to install the dependencies for the vkvg library:

This is how i thought building the necessary libraries was easier to start coding. The problem i am currently facing is that fontconfig is not working (it cannot find the fonts). I assume this is because the library was built for Linux or the vcpkg package manager does not set up properly the fontconfig library. Should i add the configuration files on the directory of the Visual Studio solution or should the tutorial define a path variable for fontconfig? How did you solve the problem on your machine?
Sorry for all these questions.

[Joaopmoliveira]

The two paths in question are:

FONTCONFIG_FILE is used to override the default configuration file.
FONTCONFIG_PATH is used to override the default configuration directory.

[jpbruyere]

I develop only on linux, I'm not aware of windows user problems, so I'm happy to have you for windows debugging :-). I have to study that question, but I'm currently on something else. I'll try to have some answers for you tomorrow.

[Joaopmoliveira]

Yeah, i will also try to find solutions. Apparently Gimp (the ide to manipulate images) solves this problem and they use fontconfig on windows, but I still haven’t gone through their code base.

[jpbruyere]

Where do you get an error? When trying fontconfig command line utility, or in vkvg samples? On linux, there's always a fallback font, is the text sample crashing?

[Joaopmoliveira]

When i call the function vkvg_device_create there is an error thrown by fontconfig called “fontconfig error: Cannot load default config file” which then causes subsequent errors to freetype on the file vkvg_fonts.c at line 41

[Joaopmoliveira]

I assume this default config file is the fonts.config which is always present on linux, but it must be placed somewhere on windows by hand

[jpbruyere]

it should have been install in a directory named 'tools/fontconfig/fonts' (from https://github.com/microsoft/vcpkg/blob/master/ports/fontconfig/CMakeLists.txt), you may use the env variables to point to it.

[jpbruyere]

Maybe we could handle this in fontconfig init in vkvg, and set env vars there pointing to a default fonts.conf shipped with vkvg, if init failed.

[Joaopmoliveira]

The solution with the env variables worked! I do have another question. You have a macro in vkvg_internal called FB_COLOR_FORMAT which is set to VK_FORMAT_B8G8R8A8_UNORM, but should this not be found at runtime? Because there is a chance that the surface being printed to is not compatible with the specific format.

[jpbruyere]

Happy to ear it. For what to be done in the vkvg init on failure, I think the best is just to show a message that tell about those env variables for finding fonts.conf.

ColorFormat:

We may at least check during the device creation that this format (also the stencil) is supported, but bgra32 is tightly bound to the color handling during draw operations. vkvg internals use floats, this choice was made to fit the middle end graphic hardware optimized for 32bit floats operations, (considering the market statement that 64bit floats are overkill for scene rendering). So there's a lot of places that limit the color components to 32bits (vertex, push constants, func calls). Also the order Blue, Green, Red, Alpha, is fixed in several places. BGRA32 should be supported on most common hardware's.
So for now, color components are 8 bits (at most), so it would be useless to use a wider component format, if vertex and other data structures are enable to address up to 8 bits per component.
However, drawing on smaller format (1->3 component, < 8bits per components) could be tested.
On the other hand, choosing the best Stencil format used to make save/restore could lead to increase performances, with more bits, more save/restore levels can be achieved without re-creating additional images. But the save/restore algorithms are not simple, and are dependent on the stencil texture format, which is fixed for now.
Color and stencil formats have been fixed to limit complexity during early developments. But at least a correct error handling on 'format not supported' exception must be provided during device creation in the current master (Is there a better fallback format?).
The testing of other texture formats should be seen as an entire development step, that stand after the current revamping of vertex (new-vertex branch) and final dash implementation. But testing rapidly other smaller formats and see how vkvg react should be quiet straight forward.

[jpbruyere]

I've put a check on FontConfig init with error message in the 'dashes' branch (https://github.com/jpbruyere/vkvg/tree/dashes)

[Joaopmoliveira]

I am sorry that I am still not contributing to the source code, still going strong on the learning curve! I have finished the tutorial to compile the library with the options for windows. I am trying to find the solutions to the incompatibility with the VK_FORMAT_B8G8R8A8_UNORM format so that I can start with the tutorials to use the library from the end user perspective.

[Joaopmoliveira]

So lets assume for now that this is the solution, but in a while should we not ship the file with the library? Or should this be the job of the developer who uses the library?

[jpbruyere]

If fontConfig has been installed by any mean, there must be a fonts.conf somewhere, so I don't think we need to provide one.
Have you experience a failure with the VK_FORMAT_B8G8R8A8_UNORM format?

[jpbruyere]

Helping with tests and docs is already very valuable, thanks a lot.

[Joaopmoliveira]

Have you experience a failure with the VK_FORMAT_B8G8R8A8_UNORM format?

Probably an error on my part when selecting the index of the Queue family, still figuring out what happened!