Manual del desarrollador

Transcripción

1 LABORATORIO DE INVESTIGACIÓN Y FORMACIÓN EN INFORMÁTICA AVANZADA Manual del desarrollador Versión r de noviembre de 2013

2 Índice general 1 Ginga Introducción Tecnologías y herramientas de desarrollo Arquitectura de Ginga.ar Variables de ambiente (Ginga settings) Configuración Implementación Diagramas de secuencia Inicio de Ginga.ar Registro de un input listener Dispatch de una tecla Creación de un player Componentes 10 2 Librería ncl30-presenter 10 3 Librería ncl30-converter 11 4 Librería ncl Librería gingaplayer 12 6 Librería canvas 13 7 Librería util 14 Referencias 17 8 ginga Documentación de las clases Referencia de la Clase Ginga Descripción detallada

3 ÍNDICE GENERAL 2 9 ncl30-presenter Documentación de las clases Referencia de la Clase br::pucrio::telemidia::ginga::ncl::adapters::application::application- PlayerAdapter Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::model::components::executionobject Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::emconverter::formatterconverter Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::model::event::formatterevent Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ginga::ncl::focus::formatterfocusmanager Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::emconverter::formatterlinkconverter Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::formattermediator Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ginga::ncl::adapters::formatterplayeradapter Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::formatterscheduler Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ginga::ncl::adapters::playeradaptermanager Descripción detallada Referencia de la Clase br::pucrio::telemidia::ginga::ncl::presentationenginemanager Descripción detallada Documentación de las funciones miembro ncl30-converter Documentación de las clases Referencia de la Clase br::pucrio::telemidia::converter::framework::documentparser Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::idocumentconverter Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::framework::moduleparser Descripción detallada Documentación de las funciones miembro

4 ÍNDICE GENERAL Referencia de la Clase br::pucrio::telemidia::converter::ncl::nclcomponentsconverter Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::nclcomponentsparser Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::ncl::nclconnectorsconverter Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::nclconnectorsparser Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::ncl::ncldocumentconverter Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::ncldocumentparser Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::ncl::nclimportconverter Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::nclimportparser Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::ncl::nclinterfacesconverter Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::nclinterfacesparser Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::ncl::ncllayoutconverter Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::ncllayoutparser Descripción detallada Referencia de la Clase br::pucrio::telemidia::converter::ncl::nclstructureconverter Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::converter::framework::ncl::nclstructureparser Descripción detallada ncl Documentación de las clases Referencia de la Clase br::pucrio::telemidia::ncl::connectors::action Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::animation::animation

5 ÍNDICE GENERAL Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::base Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::connectors::causalconnector Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::connectors::compoundaction Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::connectors::conditionexpression Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::connectors::connector Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::connectors::connectorbase Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::descriptor::descriptorbase Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::entity Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::descriptor::genericdescriptor Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::layout::layoutregion Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::link::link Descripción detallada Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::ncldocument Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::layout::regionbase Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro

6 ÍNDICE GENERAL Referencia de la Clase br::pucrio::telemidia::ncl::switches::rule Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::switches::rulebase Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase br::pucrio::telemidia::ncl::connectors::simpleaction Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::transition::transition Descripción detallada Referencia de la Clase br::pucrio::telemidia::ncl::transition::transitionbase Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro gingaplayer Documentación de las clases Referencia de la Clase player::device Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase player::input::manager Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase player::player Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase player::property Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase player::soundproperties Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase player::surfaceproperties Descripción detallada Documentación del constructor y destructor

7 ÍNDICE GENERAL Documentación de las funciones miembro Referencia de la Clase player::system Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro connector Documentación de las clases Referencia de la Clase connector::editingcommanddata canvas Documentación de las clases Referencia de la Clase canvas::canvas Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::font Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::fontmanager Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::mediaplayer Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::player Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::surface Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::system Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::videooverlay

8 ÍNDICE GENERAL Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::webviewer Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase canvas::window Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro util Documentación de namespaces Referencia del Namespace util::cfg Descripción detallada Documentación de las funciones Referencia del Namespace util::log Descripción detallada Documentación de las clases Referencia de la Clase util::process Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase util::net::socket Descripción detallada Documentación del constructor y destructor Documentación de las funciones miembro Referencia de la Clase util::tool Descripción detallada Documentación de las funciones miembro Documentación de archivos Referencia del Archivo src/cfg/cfg.h Descripción detallada Referencia del Archivo src/log.h Descripción detallada

9 GINGA 1.1. Introducción Ginga es una especificación de un middleware que permite la ejecución de aplicaciones interactivas en un receptor de TV Digital terrestre. La especificación de Ginga se encuentra descripta en la norma ABNT NBR Los receptores de TV Digital, que funcionan de acuerdo al Sistema Argentino de Televisión Digital Terrestre (SATVD-T), deben contar con una implementación del middleware Ginga. Ginga.ar es una implementación de dicho estándar, desarrollada por el laboratorio LIFIA de la Universidad Nacional de La Plata, a partir de la implementación de referencia de Ginga-NCL creada por la PUC de Rio de Janeiro. Ginga.ar está desarrollado en C++, es Software Libre y las licencias utilizadas son GPLv2 y LGPLv2. Ginga.ar permite ejecutar aplicaciones interactivas escritas en NCL (Nested Context Language). NCL es un lenguaje de aplicación XML con elementos diseñados para la especificación de los aspectos de la interactividad, la sincronización espacio-temporal de los objetos multimedia, la adaptación y soporte para múltiples dispositivos. Ginga.ar fue portado a diversas plataformas de STB equipadas con chip-sets diferentes, entre ellos ST7101, ST7102, ST7105 y ST7108 que poseen una arquitectura SH4. También a chip-sets de arquitectura ARM, como los CS1200 y CS1800. Ginga.ar además se ejecuta en distribuciones Linux desktop de 32 y 64 bits, además de Windows. Este documento presenta la arquitectura, herramientas y librerías necesarias para el desarrollo y extensión de Ginga.ar. También se incluyen detalles sobre los principales módulos y clases que lo componen. Finalmente, se explica, mediante diagramas de secuencia UML, cómo interactuan diferentes componentes del middleware para ciertos casos de interés Tecnologías y herramientas de desarrollo Para el desarrollo de Ginga se puede utilizar un entorno de desarrollo integrado (IDE), como Eclipse-CDT o Kdevelop, así también como trabajar desde un editor de texto y una terminal. Mínimamente se requiere de un compilador C++, preferiblemente GCC a partir de la versión 4.6.3, un interprete de python (a partir de la versión 2.7.3), y CMake a partir de su versión 2.8. Con estas tres herramientas más las librerías externas requeridas (listadas luego), se tiene todo lo necesario para compilar el código fuente de Ginga 2.0. Las librerías externas requeridas son las siguientes: 1. Componentes de Boost (a partir de la versión 1.46): a) System b) Filesystem (versión 3)

10 1.3 Arquitectura de Ginga.ar 9 c) Thread d) Math_tr1 2. XercesC (a partir de la versión 2.8) 3. LibEV 4. WebKit 5. Gtk2 6. LibVLC 7. Lua51 8. Curl 1.3. Arquitectura de Ginga.ar Ginga.ar posee una arquitectura diferente a la versión original publicada por el Telemedia Lab de la PUC-Rio. Los módulos que componen la arquitectura de Ginga.ar se describen a continuación: util: implementa un conjunto muy variado de funciones, las cuales, son utilizadas por el resto de los módulos. Se pueden destacar: el manejo de buffers, control de procesos, loop de eventos, entre otras. canvas: implementa la funcionalidad que permite crear y controlar una interfaz gráfica. La funcionalidad incluye: manejo de ventanas, entrada de teclado, dibujo 2D, rendering de video, etc. Dicha funcionalidad se implementa en diferentes motores gráficos, lo que abstrae al usuario de esta librería del motor gráfico subyacente. gingaplayer: permite la reproducción de diferentes tipos de objetos multimedia, como ser: imágenes, scripts de Lua, video, audio, texto, páginas HTML. Para esto, la librería gingaplayer hace un extenso uso de la librería canvas. ncl30: este módulo provee un modelo de objetos para representar los componentes del lenguaje NCL30. Mediante el mismo es posible representar una aplicación NCLua. ncl30-converter: se encarga de realizar el parsing del documento NCL. De la interpretación del archivo XML, se crea el modelo de objetos que representa a la aplicación interactiva. Para esto se utilizan las clases definidas en la librería NCL30. ncl30-presenter: implementa el motor de ejecución de las aplicaciones NCLua. Controla el ciclo de vida de todos los objetos multimedia, sus respectivos eventos y la forma de interacción entre ellos. Figura 1.1: Arquitectura de Ginga.ar La figura 1.1, presenta la organización de los mismos. Los módulos cuyo nombre lleva el prefijo dtv fueron desarrollados por el Lifia.

11 1.4 Variables de ambiente (Ginga settings) Variables de ambiente (Ginga settings) Existen un conjunto de variables de ambiente, como por ejemplo system.language (lenguaje del audio) o system.subtitle (lenguaje del subtítulo), que están disponibles para las aplicaciones NCLua, accesibles tanto desde NCL como desde scripts Lua. Las variables se dividen en siete grupos: system, user, default, service, si, channel y shared, cada uno con semántica y características diferentes. Para más información sobre los settings puede consultarse la ABNT NBR : Configuración Los valores de las variables son configurables por medio de un archivo de conguración XML (ver capítulo 7) donde cada grupo de variables es un nodo que desciende del nodo root. Las variables de cada grupo son nodos que contienen un valor y descienden del nodo de su grupo. Ejemplo de archivo de configuración para las variables de settings <?xml version="1.0" encoding="utf 16" standalone="no"?> <root> <settings> <focusbordertransparencyasfloat>0</focusbordertransparencyasfloat> </settings> <si> <numberofservices>0</numberofservices> <numberofpartialservices>0</numberofpartialservices> <channelnumber>0</channelnumber> </si> <service> <currentfocus>0</currentfocus> <currentkeymaster></currentkeymaster> </service> <default> <focusbordercolor>white</focusbordercolor> <selbordercolor>white</selbordercolor> <focusborderwidth> 3</focusBorderWidth> <focusbordertransparency>0</focusbordertransparency> </default> <system> <audiotype>stereo</audiotype> <audiotype0>stereo</audiotype0> <operatingsystem></operatingsystem> <luaversion>5.1</luaversion> <nclversion>3.0</nclversion> </system> </root> Implementación En el archivo settings.cpp, ubicado en la ruta lib/dtv-gingaplayer/src/player, es donde son definidas e inicializadas las variables; cada grupo es representado por un nodo del árbol de configuración, mientras que los

12 1.5 Diagramas de secuencia 11 valores del mismo son propiedades de dicho nodo; se puede añadir una nueva variable agregando una nueva propiedad al nodo o crear un nodo para conseguir un nuevo grupo de valores. La inicialización de los valores de cada variable puede hacerse al momento de la creación de la propiedad o en la función player::settings::load. Por otro lado, si lo que se desea es modificar un valor ya existente, simplemente bastará con buscar la inicialización de la variable y cambiar su contenido. Si sólo se ha modificado un valor de una propiedad o agregado una nueva propiedad a un grupo existente, entonces ésta ya estará disponible para ser usada en las aplicaciones NCLua, sin embargo, agregar un nuevo grupo de variables implica exportarlo a una tabla Lua para poder ser utilizado desde un script, la clase encargada de esto es player::settings::module, la cual se encuentra en la ruta lib/dtvgingaplayer/src/player/lua/settings. Durante la inicialización del módulo se llama al método exporttables, en él se hace uso de la clase player::settings::utilcfg2lua para exportar la tabla mediante el método exportkey; es aquí donde se debe agregar un llamado extra a éste método para que exporte la clave del nuevo grupo Diagramas de secuencia Inicio de Ginga.ar En el siguiente diagrama de secuencia se observa el inicio de ejecución de Ginga.ar. Se instancian los principales objetos de gingaplayer como System y Device. Luego se inicia la presentación del documento mediante el objeto PresentationEngineManager.

13 1.5 Diagramas de secuencia 12

14 1.5 Diagramas de secuencia Registro de un input listener El siguiente diagrama de secuencia muestra como se registra como input listener un ApplicationPlayer- Adapter. Este objeto que controla la ejecución de scripts Lua, es agregado a la colección de listeners que tiene el objeto dtv-gingaplayer::input::manager.

15 1.5 Diagramas de secuencia Dispatch de una tecla El siguiente diagrama muestra la interacción que tiene lugar cuando se presiona una tecla en una aplicación. Se puede ver como la misma es recibida por el listener ApplicationPlayerAdapter, registrado en el diagrama anterior.

16 1.5 Diagramas de secuencia Creación de un player En el siguiente diagrama se muestra como se crea un player una vez iniciada la ejecución de Ginga.ar.

17 COMPONENTES 2 Librería ncl30-presenter Esta librería realiza la presentación de documentos NCL. Esto es iniciar, pausar o detener la aplicación ginga definida en el documento NCL. Es la encargada de iniciar el parsing del documento, indicándole el nombre del archivo NCL al módulo ncl30-converter. Interactúa con los módulos ncl30 y gingaplayer al leer las propiedades del modelo NCL y luego aplicarlas a los players. En esta librería se definen también, clases para el manejo de los eventos descriptos en la especificación Ginga, entre los cuales están: Eventos de presentación. Eventos de selección. Eventos de seteo de propiedades. Figura 2.1: Diagrama de las principales clases de la librería ncl30-presenter.

18 17 3 Librería ncl30-converter Esta librería es la encargada de realizar el parsing del documento NCL. Es una de las primeras tareas que se realiza al iniciar Ginga. Tiene como responsabilidad leer y analizar el documento NCL, detectando posibles errores sintácticos que no estén acorde a lo que especifica la norma. A medida que se realiza el parsing se van instanciando las clases de ncl30 correspondientes y se van aplicando las propiedades leídas del documento NCL. Para realizar el parsing se trata al documento como un archivo XML. Se comienza leyendo el head del archivo buscando por alguno de los elementos clave: importeddocumentbase. regionbase. rulebase. transitionbase. descriptorbase. connectorbase. meta. metadata. Y luego, a su vez dentro de cada uno de ellos, los elementos correspondientes a cada sección. Una vez terminado el parseo del head, se procede a analizar el body buscando las siguientes secciones: media. context. switch. Cuando se termina de realizar el parsing se retorna un valor indicando si se produjo algún error. Figura 3.1: Diagrama de las principales clases de la librería ncl30-converter.

19 18 4 Librería ncl30 Esta librería es la encargada de modelar un documento NCL. Contiene clases para representar cada sección de dicho documento, tal como regiones, descriptores, medias, transiciones, etc. Los objetos de esta librería prácticamente no tienen comportamiento, ya que su único propósito es el de modelado de datos. La clase principal es NclDocument, que como su nombre lo indica representa al documento NCL. A partir de la instancia de dicha clase se referencian los objetos que representan cada sección del NCL, armando así el modelo. Cada objeto guarda información sobre las propiedades que le fueron seteadas desde el archivo NCL. Por ejemplo LayoutRegion tiene información sobre las dimensiones de la región. ncl30-converter es el encargado de instanciar las clases de ncl30 a medida que realiza el parsing. Figura 4.1: Diagrama de las principales clases de la librería ncl30. 5 Librería gingaplayer La librería gingaplayer permite la reproducción de diferentes tipos de medios (imágenes, scripts de lua, video, audio, texto, páginas html y animaciones), haciendo uso, para ello, de la librería canvas, proveyendo una capa de abstracción sobre la misma. La clase principal de gingaplayer es la clase abstracta Player. Esta clase posee varias subclasificaciones correspondiéndose con cada tipo de medio posible. En el primer nivel de subclasificación nos encontramos con los medios gráficos y los medios de sonido. Los medios gráficos son representados por la clase abstracta GraphicPlayer, la cual tiene propiedades visuales (SurfaceProperties). Estas propiedades le dan al player la capacidad de renderizado y control de la superficie de renderizado. Los medios de sonido, por su parte, están representados por la clase SoundPlayer, la cual posee propiedades de sonido (SoundProperties). Estas propiedades permiren que el player pueda controlar propiedades de sonido. Un caso particular es el de la clase VideoPlayer, la cuál subclasifica a GraphicPlayer, pero además también posee una propiedad de sonido para la correcta reproducción de videos. Todas las instancias de las subclases de Player son administradas por un Device, que es el encargado de

20 19 crear e inicializar canvas::system 1 (principal objeto de la librería canvas que da soporte a gingaplayer). La librería gingaplayer permite el uso de varios Device simultáneamente, siendo System la clase encargada de administrar los mismos. Otras de las funciones de System son la de iniciar el loop principal de canvas::system, registrar timers y administrar sockets, entre otras. Figura 5.1: Diagrama de las principales clases de la librería gingaplayer. 6 Librería canvas La librería canvas encapsula funcionalidades de: dibujo (gráficos en 2D), reproducción de multimedia, manejo de ventanas y manejo de eventos (timers, sockets y entrada de teclado). La clase principal de la librería canvas es System. Esta clase es la encargada de ejecutar el loop principal, registrar timers, crear sockets y notificar eventos. También provee un despachador de tareas, permitiendo que se encolen tareas para ser ejecutadas en el thread del loop principal. A partir de una instancia de la clase System, se crean las instancias de las siguientes clases mas importantes de la librería; estas son (Window, Canvas, Player y WebViewer). La funcionalidad de dibujo en 2D se realiza a través de las clases Canvas y Surface. La clase Canvas es la encargada de administrar las instancias de la clase Surface, permitiendo crear las mismas y componerlas para obtener la imagen final a mostrar en una ventana. Las ventanas están representadas mediante la clase Window. Esta clase permite realizar el manejo básico de 1 No confundir la clase canvas::system con la clase System perteneciente a gingaplayer.