Using the library with C++

If you prefer to write your code in C++ and use the Lumia Imaging SDK, then this article is for you.

At the time of writing, the Lumia library does not contain C++ API sample code. However, this article provides enough information for a C++ developer to get started using the C++ API.

The Imaging SDK as a Windows Runtime library

While the Lumia Imaging SDK has been written fully in C++, it is not provided as a regular Win32 C++ library but as a Windows Runtime (WinPRT/WinRT) component for Windows Phone and Windows. WinRT enables C++ components to communicate with components written in other languages (for example: C#, Visual Basic).

Dn859607.windows_phone_runtime(en-us,WIN.10).png

The Lumia Imaging SDK's core APIs are available to C++ developers through any of the options given to consume WinRT components. One such option is Visual C++ component extensions (C++/CX), a set of language extensions that offer a simple and succinct syntax to access WinRT components:

  • C++/CX components can consume any WinRT type, or create classes, structs, interfaces, and other user-defined types that can be consumed by other (C++/C#/VB) components.
  • A library written in C++/CX can also use standard C++ classes and structs as long as they don't have public accessibility.
  • The signatures of the classes and methods exposed by a WinRT library are completely defined in the Windows metadata files (.winmd) which replace the familiar C++ header files.

The Imaging SDK provides Lumia.Imaging.winmd and Lumia.InteropServices.WindowsRuntime.winmd metadata files, containing interface definitions matching the Lumia::Imaging and Lumia::InteropServces::WindowsRuntime namespaces, respectively.

Note: It is not possible to access from C++ the classes defined in the Lumia.Imaging.Managed namespace. They are only intended to be used in the Microsoft.NET framework.

Since the public API surface is defined with WinRT rules, the types that can be passed into and out of the API are limited. For example, native C++ arrays, vectors and other memory regions cannot be passed directly, and must be passed as IBuffers. In many cases, copying this data during the call can be avoided, as an IBuffer can be set up to wrap the native underlying data.

Advantages of C++ API

The C++ API has the following advantages:

  • Allows reuse of existing effects/filters that were written in C++ from other projects.
  • Allows more precise control over when buffers are created and freed.
  • NEON instructions or other SIMD instructions can be used to accelerate the throughput of custom filters.
  • It may be easier to write cache-friendly code due to the high level of control over memory management that is available.
  • In general the code is optimized better by the compiler. Note that well written C# is fairly efficient, so in most cases this is likely to result in only modest gains.
  • Images from the camera can be processed faster, as they are not first converted to JPG.

C++ documentation and API reference

This library contains C++ API reference documentation, but sample code is only in C#.

As long as the C++ project has a reference to the .winmd metadata files, Visual Studio will know everything about the Imaging SDK classes and methods.  As in C#, Intellisense will display the function call parameters documentation.  When Intellisense is not enough for your needs, you can browse the C# API samples from the Lumia Imaging SDK API Reference, the C# samples are fully valid for the C++/Cx use. Beside the small syntax differences that are specific to the language used, the functionality provided by the SDK is exactly the same, regardless of the language.

For general information about working with C++/CX, see Microsoft's Visual C++ component extensions (C++/CX).

Note: When adding Imaging SDK NuGet package to Windows 8.1 Store App C++ project, you need to unload the project from the solution and then reload it to be able to use the Imaging SDK.