Revision as of 02:58, 22 November 2012

Windows Phone 8 SDK adds two new sets of APIs to develop applications using native code. This article will explain how to use C++ under Windows Phone and some general directions that any C++ developer should know when targeting the platform.

Note: This is a community entry in the Windows Phone 8 Wiki Competition 2012Q4

Introduction

Windows Phone 8 SDK adds two new sets of APIs to develop applications using native code. This article will explain how to use C++ under Windows Phone and some general directions that any C++ developer should know when targeting the platform.

WIndows Phoen 8 SDK API is divided into three part. These APIs are complementary :

• .Net gives interaction with Windows phone functionality like live tiles, send sms, ...
• Windows Phone runtime is a intermediate API which gives access to low level functionality like voice Command, voip,...
• Native code gives access to low level API like socket, Direct X, ...

For more information read :Windows Phone API reference

.Net (C# & VB)

.Net API is the original Windows Phone framework. It lets you to develop GUI with XAML technologies, access principal functionality (live tiles, tasks, send Mail, sms, ...) and XNA. It's actually the most important framework to develop Windows Phone application. To develop with this framework you can use C# or VB. You can find .net reference documentation here :

• .NET API for Windows Phone

Note : XNA is always supported, but only to develop Windows Phone 7 application. It's replaced by Direct3D with Windows Phone 8 .

Windows Phone runtime (c# ,VB & C++/CX)

This API have two functionalities :

• share API with windows 8. A subset of this api is shared with windows 8.
• mixes managed and native code. Managed and Native code are incompatible by nature but this API can be consumed by both.

This API is based on COM-like technology. Like COM is not user-friendly, Microsoft have created Visual C++ Language Reference (C++/CX) to Consume this API with C++ and create WinPRT components. This extension adds to C++ managed concept like garbage collector, properties, delegate, event.... To be consumed by manged code, class developed in C++/Cx generate metadata. In fact, VS translate this class to a COM-like Objet and generate binary.

To develop in C++ you will always use this extension somewhere because it's your C++ code which is consumed by managed API and not the other way round.

Native (C++)

Visual studio 2012 have a really good support of C++ language and its recent normalization. For windows phone, these links are good entries to find supported features :

• C/C++ Languages
• Standard C++ Library Reference
• C++ Language Reference

C++11 adds a lot of really good concepts and features. Too learn more and update your abilities, you should read this link : Modern C++.

Native API is developed in C++ and divided into libraries :

• Win 32 & COM api : subset of Win32 API. This library gives acces to function to manipulate files, raw sockets and COM object.
• Direct3D 11: 3D rendering.
• Microsoft Media Foundation APIs  : Microsoft framework for audio/video capture and rendering. Windows Phone implement a subset of Windows 8 version.
• Windows Runtime C++ Template Library : helper to consume and create COM or Windows Runtime component in C++( without CX extension). It's replace old ATL API. With Windows Phone, this library is generally use only to consume COM and WinPRT components.
• Parallel Patterns Library : high level multithread library with concurency algorithm and task concept.

In few cases, you must use directly COM Object :

• access to camera
• access to audio.

Native application

To launch an application, Windows phone need an "entry point" it may consume. To perform it, your "entry point" will be developed with C++/CX and C++ main function is replaced by a C++/CX version :

[Platform::MTAThread]
int main(Platform::Array<Platform::String^>^)
{
	auto factory= ref new myFactory();
	CoreApplication::Run(direct3DApplicationSource);
	return 0;
}

• Platform::MTAThread : metadata about application multi-thread apartment.
• myFactory: implement IFrameworkViewSource. This class is a factory use to instantiate a Iframeworkview.

ref class myFactory sealed : Windows::ApplicationModel::Core::IFrameworkViewSource
{
public:
    virtual Windows::ApplicationModel::Core::IFrameworkView^ CreateView()
    {
         return ref new myView();
    };
};

• CoreApplication::Run : C++/CX function which acquire an Iframeworkview from an IFrameworkViewSource factory.

IFrameworkView is the display provider use to make Direct3D rendering. Interface function are :

• Initialize : initialization function. take aCoreApplicationView in parameters. You can use CoreApplicationView Activated event to be notified when application is activated and use this function to register your IFrameworkView with CoreApplication events to handle application state changes.

void myView::Initialize(CoreApplicationView^ applicationView)
{
	applicationView->Activated +=
		ref new TypedEventHandler<CoreApplicationView^, IActivatedEventArgs^>(this, &myView::OnActivated);
 
        //handle suspending and resuming application states.
	CoreApplication::Suspending +=
		ref new EventHandler<SuspendingEventArgs^>(this, &myView::OnSuspending);
 
	CoreApplication::Resuming +=
		ref new EventHandler<Platform::Object^>(this, &myView::OnResuming);
}

• Load : load and activate external resources. This function is called before Run().

• SetWindow : sets the current CoreWindow. Use it to handle application display event like close, visibility change, mono-touch event, ...

void myView::SetWindow(CoreWindow^ window)
{
	window->VisibilityChanged +=
		ref new TypedEventHandler<CoreWindow^, VisibilityChangedEventArgs^>(this, &myView::OnVisibilityChanged);
 
	window->Closed += 
		ref new TypedEventHandler<CoreWindow^, CoreWindowEventArgs^>(this, &myView::OnWindowClosed);
 
	window->PointerPressed +=
		ref new TypedEventHandler<CoreWindow^, PointerEventArgs^>(this, &myView::OnPointerPressed);
 
	window->PointerMoved +=
		ref new TypedEventHandler<CoreWindow^, PointerEventArgs^>(this, &myView::OnPointerMoved);
 
	window->PointerReleased +=
		ref new TypedEventHandler<CoreWindow^, PointerEventArgs^>(this, &myView::OnPointerReleased);
}

• Uninitialize : uninitializes ressources.
• Run : start your view. Your must implement an application event-loop here.

void myView::Run()
{
        //reference time.
	BasicTimer^ timer = ref new BasicTimer();
 
	while (!m_windowClosed)//while application is not closed
	{
		if (m_windowVisible)// application is visible, update Direct3D rendering
		{
			timer->Update();
			CoreWindow::GetForCurrentThread()->Dispatcher->ProcessEvents(CoreProcessEventsOption::ProcessAllIfPresent);//process current system events
			m_renderer->Update(timer->Total, timer->Delta); //update your render from time reference.
			m_renderer->Render();// Direct3D rendering
			m_renderer->Present(); // This call is synchronized to the display frame rate.
		}
		else // application is not visible
		{
			CoreWindow::GetForCurrentThread()->Dispatcher->ProcessEvents(CoreProcessEventsOption::ProcessOneAndAllPending); ;//process current system events and wait new events.
		}
	}
}

Native application have three importants points:

• you can only use Direct3D for display data. Native API doesn't have API to build GUI.
• you must execute system events.
• You don't have access to .Net functionality. You can't use live tiles, send a SMS, ...

Without .Net functionality, native applications are not so cool and you are limited to Direct3D develop ... But remember, you can develop WinPRT components with C++/CX. So it's possible to encapsulate your c++ Code with C++/CX and consume it with managed code :p

Other wiki resources about Direct3D development:

• DirectX Developers - DirectX in Windows Phone
• Windows Phone Native C++ and DirectX - First Direct3D App, setting up Touch and Sensors

Mixed application

You can develop mixed application where your managed code consume Windows Phone Runtime components. To develop with C++ Code, you must create a Windows Phone Runtime Component which interface C++ part with a public sealed C++/CX class . It's important to readC++ extension documentation to understand its specificities :

• a C++/CX class/struct is declared with ref keyword

ref class myclass 
{
    //...
};

• Allocation is performed by ref new.
• C++/CX struct can be use like a POD.
• Class instance is handled by ^ type ( is known as a "hat"). This type is a smart pointer with a counting reference like std::shared_ptr.

myclass ^ myClass = ref new myclass ();

• Platform::String Class replace std::wstring. C++/CX String are Unicode.
• C++/CX collections are compliant with STL.
• Fundamental types are similar.
• A property is similar to getter/setter in C++.
• A delegate is a function object. It can encapsulate n C++/CX or managed code.
• An event is a delegate collection which perform all delegate when event is raised.
• sealed keyword : a sealed class or a sealed function can't be overridden.

To be consumed by managed code, C++/CX code generate a set of metadata. This generation depend on access modifier :

Metadata are generated only for specific C++/CX objects. A C++/CX class can declare C++ object only if the member/function have a private or internal access. Your public Class/Struct must be sealed because Managed code can't override it.

//C++/CX class declaration which can be consumed by managed code
public ref class MyClass sealed
{
private : //  C++ object can be used
    std::string aString:
    std::vector<uint32_t> aFunction();
 
public : //object and function are accessible by managed coe. if a c++ object is used, error is generated.
    property Platform::String ^ anotherString;
    Windows::Foundation::Collections::IVector<uint32> ^anotherFunction();
//...
};

Public access is very strict, and only specific C++/CX objects can be used  :

• function,
• property,
• delegate,
• event,

These Objects must be defined with these types :

• Fundamental,
• Windows Phone Runtime API objects ,
• C++/CX namespace reference with restriction. When class is not compatible, it generally implement an Interface declared in Windows Phone Runtime API,
• Your public sealed class/struct.

Once your components is referenced by your managed application, you can consume it like other Managed object. It's so possible to bind public properties with XAML and connect to public events.

You can find interesting explanation here :

• Creating Windows Runtime Components in C++
• C++/CX Part 0 of n: An Introduction
• C++/CX Part 1 of n: A Simple Class
• C++/CX Part 2 of n: Types That Wear Hats
• C++/CX Part 3 of n: Under Construction
• C++/CX Part 4 of n: Static Member Functions

Warning : Windows phone implement a subset of the Windows 8 C++/CX namespace. Few object are not accessible.

Collections

Windows Phone Runtime API doesn't implement collections class. To transfer collection between managed and native code, a set of collections Interface are defined. These interface have Equivalent in managed. For example IVector besome an IList in C#.

C++/CX collections use C++ parts and can't be consumed directly by managed Code. Like these classes implement a Windows Phone Runtime interface, you can cast these to be consumed through the interface

Windows::Foundation::Collections::IVector<int>^ Class1::GetInts()
{
   auto vec = ref new Platform::Collections::Vector<int>();
    ...
    return  vec;// implicit  cast to Windows Phone Runtime interface. Managed code can consume collection returned.
}

Remarque : STL collection can be converted to its C++/CX equivalent. When you convert a temporary collection, You can use std::move to avoid unnecessary internal copy

Windows::Foundation::Collections::IVector<int>^ Class1::GetInts()
{
    st::vector<int> vec;
    for(int i = 0; i < 10; i++)
    {
        vec.push_back(i);
    }    
    // Implicit conversion to IVector
    return ref new  Platform::Collections::Vector<int>(std::move(vec));
}

Debugger

You can't debug managed code and native code in same times. To selected which debugger you want use :

1. open project properties
2. open debug tab and select debugger mode

Direct 3D

Direct3D rendering can be display by two XAML controls:

• DrawingSurface. Direct3D will be rendering on DrawingSurface region. This element is used like other UI control and can you can perform transformation, animation,... This control use a Windows::Phone::Graphics::Interop::IDrawingSurfaceContentProvider and a Windows::Phone::Input::Interop::IDrawingSurfaceManipulationHandler

• DrawingSurfaceBackgroundGrid:Direct3D is rendering on all your application background. This layout must be the root UI node in XAML. You can add UI control like a Grid. This control use a Windows::Phone::Graphics::Interop::IDrawingSurfaceBackgroundContentProvider and a Windows::Phone::Input::Interop::IDrawingSurfaceManipulationHandler

Managed code can't access directly to Direct 3D. You must develop a WinPRT component which consume Direct3D with C++ code. You component must implement two interface :

• Windows::Phone::Graphics::Interop::IDrawingSurfaceBackgroundContentProvider or Windows::Phone::Graphics::Interop::IDrawingSurfaceContentProvider : class must implement these interfaces in order to be used as a content provider for the DrawingSurfaceGrid /DrawingSurfaceBackgroundGrid control.
• Windows::Phone::Input::Interop::IDrawingSurfaceManipulationHandler : interface to receive manipulation events from the DrawingSurface/DrawingSurfaceBackgroundGrid control.

Unfortunately, integration with XAML is more complicated. You need a layer of Interopility to acces to Direct3D device ( Direct3DContentProvider.h class in VS project) ... You can find information here : Direct3D with XAML apps for Windows Phone 8.

Reference links

Ressources about C++ Direct3D developpement on Windon sPhone  :

• Inside Windows Phone 42 - Sam George on Native C++ Game Development in Windows Phone 8

The media player is loading...

• Windows Phone 8: Native C/C++ Game Development

The media player is loading...

• Direct3D app development for Windows Phone 8