Documentation is needed

[romainguy]

We need to write on-boarding documentation in the Wiki section of the project. Most notably:

• How to setup an Engine, Renderer and View with SDL or equivalent
• How to setup an Engine, Renderer and View with Android
• How to create/load geometry (VertexBuffer and IndexBuffer)
• How to create, compile and load a simple material
• Better, simpler, stand-alone samples

[cgmb]

I recently integrated filament into my GLFW application. A "Getting Started" guide would definitely have saved me time. There were a few specific things I noticed:

1. The README is missing the creation of vertexBuffer and indexBuffer. IMO, those are of similar importance to the other parts of setup that are included.

2. The sample apps are very nice, but they depend on the ~2000 LOC in samples/app/. Even samples/vk_hellotriangle.cpp is hard to follow because some important initializations are done inside abstractions in the sample app. I like having those larger examples, but a Getting Started guide with a complete ~200 LOC hellotriangle.cpp with no dependencies and very little abstraction would be a wonderful addition.

3. The ways transforms are done in the samples seems different from what's stated in the class documentation for TransformManger, which shows using TransformManger::create. TransformManger::getInstance says it can return an invalid instance if the component doesn't exist, but none of the samples seem to call create, so it's not clear why a valid component is returned. I like the way the samples do it, but I would not have assumed this would work based on the docs:

   auto& tcm = engine->getTransformManager();
   tcm.setTransform(tcm.getInstance(renderable),
   math::mat4f::rotate(M_PI_4, math::float3{0, 0, 1}));

[romainguy]

We definitely need to write better samples and documentation. Right now a good starting point is android/samples/hello-triangle (except it's in Kotlin not C++ :).

For #3, the reason it works is that we automatically create a transform component for renderables when we load meshes in the sample apps (MeshAssimp.cpp and MeshIO.cpp). Which emphasizes your point about creating simpler sample apps so it's easier to understand what's going on.

[romainguy]

Looking more closely you are right some samples use the transform manager without creating the component first. I'll check what's going on there.

[romainguy]

Nevermind I remember now. When creating a Renderable, a TransformManager component is automatically added if the entity doesn't have one alredy. We need to document this.

[prideout]

As a side note, one cool thing about GitHub wikis is that they are cloneable, so we can use our favorite text editors to work on the wiki:

https://gist.github.com/subfuzion/0d3f19c4f780a7d75ba2

[pixelflinger]

@cgmb, at some point I decided that creating a Renderable would always create a Transform component -- because that's what we want 99% of the time. I didn't update the doc at the time. So, for Renderables, it should never be invalid.

[Raki]

I recently integrated filament into my GLFW application. A "Getting Started" guide would definitely have saved me time. There were a few specific things I noticed:

1. The README is missing the creation of vertexBuffer and indexBuffer. IMO, those are of similar importance to the other parts of setup that are included.
2. The sample apps are very nice, but they depend on the ~2000 LOC in samples/app/. Even samples/vk_hellotriangle.cpp is hard to follow because some important initializations are done inside abstractions in the sample app. I like having those larger examples, but a Getting Started guide with a complete ~200 LOC hellotriangle.cpp with no dependencies and very little abstraction would be a wonderful addition.
3. The ways transforms are done in the samples seems different from what's stated in the class documentation for TransformManger, which shows using TransformManger::create. TransformManger::getInstance says it can return an invalid instance if the component doesn't exist, but none of the samples seem to call create, so it's not clear why a valid component is returned. I like the way the samples do it, but I would not have assumed this would work based on the docs:

auto& tcm = engine->getTransformManager();
tcm.setTransform(tcm.getInstance(renderable),
    math::mat4f::rotate(M_PI_4, math::float3{0, 0, 1}));

Hi, @cgmb I'm trying to use filament with GLFW,

 glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
 window = glfwCreateWindow(TargetWidth, TargetHeight, "Hello World", NULL, NULL);
 winHandle = glfwGetWin32Window(window);
 engine = Engine::create();
 swapChain = engine->createSwapChain(winHandle);

...... ......

  while (!glfwWindowShouldClose(window))
 {
       update();
       if (renderer->beginFrame(swapChain))
     {
    renderer->render(view);
    renderer->endFrame();
     }
  }

' But I'm getting the 'wglMakeCurrent( )' failed error

class utils::PostconditionPanic in virtual void filament::PlatformWGL::makeCurrent(Platform::SwapChain , Platform::SwapChain ):184 in file E:\FilamentSpace\filament-master\filament\src\driver\opengl\PlatformWGL.cpp reason: wglMakeCurrent() failed. hdc = 00000000001D0B56

Please help me if you have any idea about cause for this error...

[cgmb]

Sorry @Raki, my target platform is Linux and I only ever hacked things together before I had to move on. But, I did get my hello triangle working with GLFW on Ubuntu. The code is very, very rough, and I have no idea if it will be of any use at all, but now it's there for anyone interested.

[Raki]

Sorry @Raki, my target platform is Linux and I only ever hacked things together before I had to move on. But, I did get my hello triangle working with GLFW on Ubuntu. The code is very, very rough, and I have no idea if it will be of any use at all, but now it's there for anyone interested.

@cgmb Thank you for the response and the example. I will go through it. I am sure it will be of some help :-) to me.

[kavaari]

@Raki and others if you are still struggling with this, here is a solution: You are passing Win32 HWND handle to createSwapChain(), instead you should pass the window's HDC handle.

[shartte]

So it is unclear to me what I need to delete to clean up, and when I can do so. When I delete an entity, do I need to delete all components manually as well, or are they automatically deleted? It seems to me that sometimes if i repeatedly create/delete entities, I hit a point where I crash in TransformManager where it is trying to setup an entity to be it's own parent. I am not however deleting transform components when I delete the entities. Should I? The documentation on TransformManager doesn't say.

[romainguy]

@pixelflinger can give you more info

[romainguy]

We also should add more API docs (libmath and let mostly)

[nitronoid]

For anyone like me who wanted to get filament working with Qt, I've created a simple hello world example based on @cgmb's repo which you can find here. I've only tested it on Linux, but in theory since both Qt and Filament are cross platform it should work on Windows too (with some tweaks to the Makefile).

[romainguy]

Thank you @nitronoid!

[Raki]

@Raki and others if you are still struggling with this, here is a solution: You are passing Win32 HWND handle to createSwapChain(), instead you should pass the window's HDC handle.

@kavaari Thank you for the suggestion. As per the filament-20190426-windows build, if we pass HDC handle, app is crashing. It is working fine with Win32 HWND. (Also need to introduce a delay of 17ms in glfw renderloop without the delay command buffer is being flooded)

[roxlu]

The issue is caused when creating your own context and using the createSwapChain(void* nativeWindow) function. Instead use the createSwapChain(int width, int height, int flags) version. See these comments and this repository that demonstrates a fix

[FireBanana]

@cgmb Thanks for the example, after smashing my head on the wall for days I found the calls I was missing.