Quick Start Guide Linux

Table of Contents

• Installation
• Integration
  • Initialization and Update
  • Rendering Surfaces
  • Rendering
• Debugging
• Deployment

This guide will show you how to

1. Add Coherent UI as a library to project
2. Create a Coherent::UI::ViewContext and create a single view
3. Create surfaces to be used by this view
4. Display the view using OpenGL in an XWindow
5. Deploy the executable

The sample for this guide is HelloHTMLOGL_Linux.

Installation

1. Unzip CoherentUI.zip in a directory of your choice. This directory is referred as CoherentInstallDir
2. Add CoherentInstallDir\include to your include directories.
3. Add CoherentInstallDir\lib to your library directories.
4. Add CoherentUI.lib to your project library inputs
5. To try the samples and use the Debugger run bootstrap.sh.

Note

For Linux HelloHTMLOGL_Linux is shipped with a makefile. It has been tested with gcc-4.6.3. However you might need to include the folders with the needed .so files to your LD_LIBRARY_PATH when linking the sample. This is done in the by executing export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/CoherentUI/:path/to/other/dependencies/. All Coherent UI samples depend on GLEW 1.9.0 on Linux.

Integration

Start by including the necessary headers:

#include <Coherent/UI/ViewContext.h>
#include <Coherent/UI/ViewInfo.h>
#include <Coherent/UI/ViewListener.h>

Initialization and Update

First, initialize CoherentUI with the appropriate factory settings via InitializeCoherentUI. If it succeeds, it returns a pointer to working ViewContextFactory, which you can later use to create view contexts.

Then create a view context with the appropriate settings and a listener for context events. The listener will be notified when the ViewContext is ready to create views:

ViewEventListener viewListener;
ContextEventListener listener(width, height, &viewListener);
Coherent::UI::ContextSettings settings;
Coherent::UI::ViewContext* context = viewContextFactory->CreateViewContext(
    settings,
    &listener,
    nullptr);

Coherent UI requires a license key as it's first initialization parameter. Starter and trial versions come with a pre-bundled "License.h" file containing the key. Pro licensees should have received their key upon purchase. All samples presume that there is a "License.h" in the Coherent/UI folder and in it there is a COHERENT_KEY string with your license. However you can type the string wherever you want and pass it to the initialization function.

The "ViewEventListener" and "ContextEventListener" are classes inherited from Coherent::UI::ViewListener and Coherent::UI::EventListener respectively. They should implement the callbacks that a Coherent UI context will invoke upon certain events. If you are uncertain on how to initialize the factory, or the context or wire simple drawing please consult the HelloHTML samples bundled in the Coherent UI package.

Coherent::UI::ViewContext::Update has to be called in the main loop. It processes the incoming events and executes the appropriate callbacks. Coherent::UI::ViewContext::FetchSurfaces checks if new rendered surfaces are available for the active views. It calls Coherent::UI::ViewListener::OnDraw and might request the creation or destruction of surfaces. The context is split in those two calls to allow the user to more easily accommodate a distinction between the logical update of the state of the views and their drawing. Check the Best Practices guide for tips on how to optimally organize calls to Coherent UI in your frame.

Note

All event handlers and callbacks are executed inside Coherent::UI::ViewContext::Update and Coherent::UI::ViewContext::FetchSurfaces.

void XAppWindow::Update()
{
    if(g_ViewContext)
    {
        g_ViewContext->Update();
        g_ViewContext->FetchSurfaces();
    }
}
int main(int argc, char* argv[])
{
    XAppWindow app(RENDER_AREA_WIDTH, RENDER_AREA_HEIGHT, "Hello OpenGL");
    /*
    ...
    */
    while (app.Frame())
    {
        app.Update();
        app.Draw();
    }
    /*
    ...
    */
}

When a context is up and running it will call the ContextReady method of listener and that is the appropriate time to create a view. To create a view you need a ViewInfo struct with the properties of the view, a URL for the view and a ViewListener for its events.

Coherent UI provides a custom protocol for URLs - coui. All files that are display through this protocol will be loaded from a custom FileHandler. The default one loads the files using the current working directory as root, so for our project - coui://html/hello.html will be read from html/hello.html using the application working directory as base.

void ContextEventListener::ContextReady()
{
    Coherent::UI::ViewInfo info;
    info.Width = m_Width;
    info.Height = m_Height;

    m_Context->CreateView(info, "coui://html/hello.html", m_ViewListener);
}

Rendering Surfaces

The ViewListener is notified for all view related events, such as when the view has been created, finished loading, etc. It is also responsible for creating and destroying the rendering surfaces for that view. There are at least two rendering surfaces for each view - while the listener is handling a surface, the next frame is being drawn on the other. On Linux Coherent UI uses shared memory to pass the drawn surfaces to the client.

void ViewEventListener::CreateSurface(bool, unsigned width, unsigned height, Coherent::UI::SurfaceResponse* response)
{
    response->Signal(Coherent::UI::CoherentHandle(shmget(IPC_PRIVATE, width * height * 4, 0600 | IPC_CREAT | IPC_EXCL)));
}

void ViewEventListener::DestroySurface(CoherentHandle surface, bool usesSharedMemory)
{
    shmctl(surface, IPC_RMID, nullptr);
}

Rendering

Coherent UI draws lazily all the views - if no change is triggered (either by an event or animation) in the view, no call to Coherent::UI::ViewListener::OnDraw will be made. In that case you must present the last received rendered frame of that view. Therefore when a Coherent::UI::ViewListener::OnDraw event occurs, we copy the frame to a texture that is going to be used during the rendering of the scene.

void ViewEventListener::OnDraw(CoherentHandle handle, bool usesSharedMemory, int width, int height)
{
    auto memory = ::shmat(handle, 0, SHM_RDONLY);
    if(g_Texture != GL_INVALID_VALUE)
    {
        glBindTexture(GL_TEXTURE_2D, g_Texture);
        glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, RENDER_AREA_WIDTH, RENDER_AREA_HEIGHT, GL_BGRA, GL_UNSIGNED_BYTE, memory);
        glBindTexture(GL_TEXTURE_2D, 0);
    }
    ::shmdt(memory);
}

When a Coherent::UI::View is no longer used it should be destroyed. Same goes for ViewContext - it should be uninitialized when no longer needed.

Note

Uninitializing the context does destroy all the views and callbacks related to it will be called.

Coherent::UI::View* view = viewListener.GetView();
g_ViewListener->Destroy();
g_ViewContext->Uninitialize();

Debugging

To use the Debugger, please make sure that you have run bootstrap.sh on your installation.

To enable debugging of the views:

1. Coherent::UI::ContextSettings::DebuggerPort to PORT - the port to be used by the remote debugger
2. Launch the Debugger available in the Debugger folder in your Cohernet UI package
3. Create your views in type http://localhost:PORT in the Debugger's address bar. Click GO.
4. A list of views currently active will be available - select the view you want to debug

Deployment

To deploy an application using Coherent UI you need to deploy the following files:

• CoherentUI.so - in same directory as the application executable
• CoherentUI_Host and all the other *.so* files and the folder locales from CoherentInstallDir\lib should be set in the `HostDirectory' member of the FactorySettings struct, that is given to InitializeCoherentUI method.