Getting Started

ImportantDue to NaCl deprecation by the Chromium project, Tizen TV will continue its support for NaCl only until 2021-year products. Meanwhile, Tizen TV will start focusing on high-performance, cross-browser WebAssembly from 2020-year products.

This topic is an introduction to creating Native Client applications for Samsung TVs. It describes the tools you need to develop and test Native Client applications, the structure of a Native Client application, and the essential C and C++ code.

Native Client (NaCl) applications are developed using HTML, JavaScript, and C or C++. The NaCl technology supports both the C and C++ languages, but using C++ is recommended, as the C++ code is easier to read and maintain.

To develop NaCl applications for Samsung Smart TVs, use the Tizen Studio with the TV Extension and Samsung NaCl SDK installed. The NaCl SDK also allows you to test your NaCl applications in Google Chrome™, on the TV emulator, or on a Samsung TV.

NoteNaCl applications can be developed without the Tizen Studio. However, if you intend the application to support Samsung TVs, you must use the Tizen Studio.

To test NaCl applications, you need at least 1 of the following environments:

Samsung-provided Smart TV developer model
TV emulator included in the Tizen Studio
Google Chrome™ Web browser

You can launch the application in Google Chrome™ from within the Tizen Studio.

You can also run the application directly from your own Web server instead of through the Tizen Studio. The Native Client flag must be enabled in the browser.

NoteThe browser version must be equal to or greater than the NaCl toolchain version used for development.

Although the Samsung NaCl toolchains produce binaries compatible with the Google Chrome™ runtime, applications requiring Samsung-specific interfaces cannot be launched in Google Chrome™.

Developing a NaCl Application

A NaCl application package must have the following files:

An "index.html" file defines the Web page that the NaCl module runs on and specifies the manifest location. The basic JavaScript methods for handling communication between application components must also be defined in either the "index.html" file or separate files. You can include other HTML5 and JavaScript elements, such as additional HTML files, CSS styles, and JavaScript code.
The ".nmf" manifest file describes the location of the NaCl binary for each processor architecture.
The "config.xml" file contains the configuration for a Samsung TV application. This file is automatically generated by the Tizen Studio, but can be omitted when testing the application in the Google Chrome™ Web browser.
At least 1 ".nexe" file, which contains binaries compiled using a NaCl toolchain. Applications that support multiple processor architectures have a ".nexe" file for each supported architecture.

NoteWhen testing a NaCl application on a Smart TV, the application is installed on the device as a signed ".wgt" package file.
To test an application in Google Chrome™, you can simply place the application files in a single directory on a Web server.

HTML Web Page

The "index.html" file is a standard HTML file. To implement NaCl plugins in the application, you must implement an embed element inside the body element for each NaCl plugin you want to include:

<embed id="nacl-app"
  width=0 height=0
  src="application.nmf"
  type="application/x-nacl" />

The embed element attributes include:

id defines an anchor ID for the HTML object.
width and height specify the dimensions for the NaCl plugin area visible on the Web page.
src defines the ".nmf" file location.
type defines the embedded content type. To embed a NaCl plugin, it must be set to application/x-nacl.

To respond to progress events and messages, you must place the embed element within a div element:

<div id="listener">
  <script type="text/javascript">
    function moduleDidLoad(event) {
      var app = document.getElementById('nacl-app');
      app.postMessage("Hello NaCl");
    }

    // Display message in popup
    function handleMessage(message) { alert(message); } 

    var listener = document.getElementById('listener');
    listener.addEventListener('load', moduleDidLoad, true);
    listener.addEventListener('message', handleMessage, true);
  </script>

  <embed id="nacl-app"
    width=0 height=0
    src="application.nmf"
    type="application/x-nacl" />
</div>

For more information on NaCl progress events, see Progress Events.

Manifest File

The manifest file is a JSON file with the ".nmf" extension. For each architecture key, the "url" key defines the location for its corresponding ".nexe" native binary file.

{
  "program": {
    "x86-32": {
      "url": "application_i686.nexe"
    },
    "x86-64": {
      "url": "application_x86-64.nexe"
    },
    "arm": {
      "url": "application_armv7.nexe"
    }
  }
}

You can include as many architectures in the manifest as you want. However, to run the application in the following scenarios, you need the modules for specific architectures:

To run the application on a Samsung Smart TV, you must support the ARM architecture.
To test the application on the TV emulator, you must support the i686 architecture.
To test the application in Google Chrome™, you must support the host system architecture.

Configuration File

The "config.xml" file is a Tizen-specific file that is created for every Tizen application. The file is automatically generated by the Tizen Studio. The following is an example of a "config.xml" file:

<?xml version="1.0" encoding="UTF-8"?>
 
<widget xmlns="http://www.w3.org/ns/widgets" xmlns:tizen="http://tizen.org/ns/widgets"
  version="1.0.0" viewmodes="fullscreen" id="http://YourDomain.com/YourApp">
  <tizen:application id="1234567890.YourAppName" package="1234567890" required_version="2.2"/>
  <feature name="http://tizen.org/feature/screen.size.normal"/>
  <tizen:setting screen-orientation="portrait" context-menu="enable" 
    background-support="disable" encryption="disable" install-location="auto" 
    hwkey-event="enable"/>
  <icon src="icon.png"/>
  <content src="index.html"/>
  <name>Your App Name Goes Here</name>
</widget>

For more information on the "config.xml" file structure, see the "Configuration Document" section in the W3C Widget Packaging and XML Configuration specification.

Implementing Native Code

NaCl plugins implement 2 main types of interfaces, which are sets of functionalities used by the plugin:

Interface names starting with PPP are provided by the plugin. They typically consist of a set of callbacks that are called by the browser.
Interface names starting with PPB are provided by the browser. They allow the plugin to use various functionalities.

Within the NaCl plugin, the module is responsible for creating interfaces and is the main entry point for a NaCl application, while the instance is a special PPP interface required by NaCl plugins. The instance interface is created by the module and logically represents an instance of the NaCl application on the Web page.

Application Code in C

A NaCl application written in C must implement 3 basic functions:

PPP_InitializeModule() is the application entry point, called when the module is loaded.
PPP_ShutdownModule() is called immediately before the module is destroyed.
PPP_GetInterface() informs the browser about the interfaces that the NaCl plugin supports, including the instance interface.

The PPP_Instance interface structure must contain pointers to the following functions, which handle important instance events:

DidCreate() is called by the browser when the instance is created.
DidDestroy() is called by the browser when the instance is destroyed.
DidChangeView() is called by the browser when the instance viewport changes (such as when it is resized).
DidChangeFocus() is called by the browser when the instance gains or loses focus.
HandleDocumentLoad() is not used in Samsung TV NaCl applications and must return PP_FALSE.

You can use additional features in your application, such as input event handling and 3D graphics, by implementing various interfaces. For example, to receive messages from the Web page, implement the PPP_Messaging interface using the HandleMessage() function, which is called by the browser when a message is received. For more information on the available interfaces, see the Pepper API documentation.

To learn how to implement a basic NaCl application in C, see the Hello World in C tutorial.

Application Code in C++

A NaCl application written in C++ must implement 2 basic classes and an entry function:

Class derived from pp::Module representing the NaCl module.
Class derived from pp::Instance representing the NaCl application instance.
CreateModule() function responsible for module creation.

Within the module object, derived from pp::Module, you must override the CreateInstance() function. This function constructs the application instance class and returns a pointer to it. To define the entry point for module creation, the CreateModule() function is implemented inside the pp namespace declaration, and returns a pointer to the created module object. These steps must be implemented in every C++ NaCl plugin.

#include "ppapi/cpp/module.h"

class HelloWorldModule : public pp::Module {
 public:
  virtual pp::Instance* CreateInstance(PP_Instance instance) {
    return new HelloWorldInstance(instance);
  }
};

namespace pp {

Module* CreateModule() {
  return new HelloWorldModule();
}

}  // namespace pp

The instance class derives from pp::Instance and defines an explicit constructor from PP_Instance that calls the base class constructor with the same argument. The pp::Instance class provides various virtual functions which can be overridden:

Init() is called with the arguments specified in JavaScript immediately after the instance object is constructed.
DidChangeView() is called when the instance viewport changes (such as when it is resized).
DidChangeFocus() is called when the instance gains or loses focus.
HandleInputEvent() is called when an input event is received from the Web page.
HandleMessage() is called when a message is received from the Web page.

For example, to react to an incoming message from the Web page, override the HandleMessage() function. The following code derives the instance class and posts the "Hello World" text when a string is received from the Web page:

#include "ppapi/cpp/instance.h"
#include "ppapi/cpp/var.h"

class HelloWorldInstance : public pp::Instance {
 public:
  explicit HelloWorldInstance(PP_Instance instance)
      : pp::Instance(instance) {}

  void HandleMessage(const pp::Var& message) override {
    if (message.is_string()) {
      PostMessage("Hello World\n");
    }
  }
};

To learn how to implement a basic NaCl application in C++, see the Hello World in C++ tutorial.

Building the Application

The package building process is automated by the Tizen Studio. For more information, see Building NaCl Projects.

If you want to test your application in Google Chrome™, you can also compile the application manually. The following sample "makefile" compiles and generates the manifest file for the "Hello World" tutorial applications: makefile (direct download)

To use the sample "makefile":

On your computer, make sure the "NACL_SDK_ROOT" environment variable is set to the appropriate Pepper API folder for your toolchain.
If you are compiling C code, in the "makefile", remove the "ppapi_cpp" text from the "LIBS" line.
Use the make command to compile the application.

Testing the Application

You can launch the application in Google Chrome™, on the emulator, or on an actual TV directly from the Tizen Studio. For more information, see Launching NaCl Projects.

If you want to run the application in Google Chrome™, you can also place the application files (the manifest, HTML, JavaScript, and native code files) in a directory on your Web server, and access the application in Google Chrome™ through its URL.

NoteTo ensure that your latest application build is run and errors are not thrown, in Google Chrome™, enable the developer tools and disable the browser cache.