Dullahan

Note: this is the Alchemy Viewer fork of Dullahan and is not a standalone project.

It is consumed as a git submodule of the Alchemy Viewer (under indra/dullahan) and is built as part of the viewer's CMake build, which supplies CEF and the other dependencies it needs. It cannot be built on its own - the old standalone autobuild scripts (build-cmd.sh, BuildParams, tools/build.*) have been removed, and CMakeLists.txt here is included by the viewer rather than configured directly.

To build it, configure and build the viewer as described in the viewer's documentation; Dullahan (and its opengl-example) are built automatically.

The rest of this document is retained from upstream Dullahan for background on what the library is and how its API is used; the standalone build instructions below no longer apply to this fork.

What is it?

A headless browser SDK that uses the Chromium Embedded Framework (CEF). It is designed to make it easier to write applications that render modern web content directly to a memory buffer, inject synthesized mouse and keyboard events as well as interact with features like JavaScript or cookies.

What could I use it for?

It might be useful in a number of situations - for example:

• Anywhere you want to render web content in a graphics application - e.g. help pages in an OpenGL based game
• VR based video chat and shared environments
• HTML/JavaScript based user interfaces E.G. a tablet based paradigm for VR
• Integration with JavaScript for automated site testing
• Web page contents analysis - E.G:
  • Capture images from the most popular 500 web pages and count the top 5 colors in each.
  • Capture a Google Maps traffic map of where you live for 24 hours and see how really miserable your commute is :)
• Web page capture to an image or a PDF file
• Lots more I haven't thought of yet

There are some examples included in this repository and there is a description and a screen shot for each here.

What is CEF?

From the CEF Wiki page: The Chromium Embedded Framework (CEF) is an open source framework for embedding a web browser engine based on the Chromium core.

An essential site to visit when developing a CEF based application is the CEF forum started and run by (I believe) the original CEF author Marshall Greenblatt who is very generous with his time and expertise.

Which platforms are supported?

• Windows 32/64 bit (primary development platform)
• macOS 64 bit (works, is supported but needs a little work - any macOS devs out there want to help?)
• Linux 64 bit (not available yet but hopefully one day - any Linux devs want to help?)

How do I build CEF?

In order to build Dullahan, you need a build of CEF. You can acquire or build a compatible version of CEF in a number of ways:

• Use the CEF package from the Spotify Automated CEF Builds page
• Clone the Linden CEF source repository and use the batch file (Windows) and Shell script (macOS) to build CEF from source code. This means building Chromium from source too which takes a long time and needs to be done on a powerful machine (E.G. builds take 12-16 hours on my 2019 MacBook Pro/BootCamp)
• You will have to build from source if you want to enable the media_codec option in builds that enables support for sites like Twitch, YouTube Live and Zoom - the Spotify packages do not have that option enabled
• Lots more information about building CEF on all platforms can be found on the cef / MasterBuildQuickStart page here

How do I build Dullahan?

In this fork you do not build Dullahan directly. It is a git submodule of the Alchemy Viewer and is built by the viewer's CMake build, which provides CEF (via vcpkg) and the other dependencies. Configure and build the viewer as described in its documentation and Dullahan - along with the opengl-example - is built automatically as part of that.

The upstream standalone build flow (the tools/build.sh / tools/build.bat scripts driven by autobuild) is not used here and those scripts have been removed.

What are the system requirements for building CEF and Dullahan?

• The requirements for building Chromium and CEF change frequently
• The requirements for building Dullahan mirror those of CEF and Chromium
• The most up to date version will always be on the cef / BranchesAndBuilding page here.

Which version of the C++ runtime library does it use on Windows?

For historical reasons, both Dullahan and the version of CEF it consumes are built with the C++ runtime library set to Multi-threaded DLL / Multi-threaded Debug DLL. If you want to build it with a different runtime library, you should examine instances of CEF_RUNTIME_LIBRARY_FLAG in the build scripts

Is there a binary version I can download?

Not right now. I used to store a pre-built version on the Windows 64 bit version in my DropBox but that became untenable. Once I figure out a sensible place to store a large binary package, I'll bundle up the latest SDK and examples for all the platforms.

How do I use it?

The short answer is look at the code in the examples folder and dullahan.h. Generally speaking, you create an instance of the library, call init() and regularly call the update() function in your own message loop. You can hook up a callback to be notified when the contents of the page changes and get access to the raw pixels. You can synthesize mouse and keyboard events and send them into the page. Finally, when you want to exit, make sure the onRequestExit callback is hooked up and call the requestExit() method. When the library and CEF have cleaned everything up, your callback will be triggered and you can call shutdown() before exiting normally.

Are there examples?

Why yes there is - take a look in the examples subdirectory of this repository. There are some screen shots and short descriptions in the README file too

Alternatives

• The most exciting alternative in this space is from Google themselves - headless Chromium and Puppeteer both appear to offer much of what Dullahan does albeit better because they have more than one person working on it :) It's very new and still developing but definitely worth a look and will likely supersede Dullahan one day.

Why the name?

Seemed appropriate