Updated text to reflect current state of LayerManagement.
Updated Version String inside doxygen Configuration, Document Version is 2.0.
Added new graphic, updated existing graphics.
Resized all graphics to 120mm width.
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
-PROJECT_NAME = "GENIVI LayerManagement"
+PROJECT_NAME = "GENIVI LayerManagement 0.9.5"
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# if some version control system is used.
-PROJECT_NUMBER = 0.9.5
+PROJECT_NUMBER = "2.0"
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
# wildcard * is used, a substring. Examples: ANamespace, AClass,
# AClass::ANamespace, ANamespace::*Test
-EXCLUDE_SYMBOLS = Vector2 _ilm_param t_ilm_param
+EXCLUDE_SYMBOLS =
# The EXAMPLE_PATH tag can be used to specify one or more files or
# directories that contain example code fragments that are included (see
# of all compounds will be generated. Enable this if the project
# contains a lot of classes, structs, unions or interfaces.
-ALPHABETICAL_INDEX = YES
+ALPHABETICAL_INDEX = NO
# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
ALIASES += frequency="\xrefitem frequency \"Expected Frequency\" \"LayerManagement Command Frequency Overview\""
ALIASES += action="\xrefitem action \"Action Taken\" \"LayerManagement Command Action Overview\""
-#ALIASES += frequency="\b Expected \b Call \b Frequency:\\"
-#ALIASES += action="\b Action \bTaken:\\"
* \brief Sets the horizontal and vertical position of the layer.
* \ingroup ilmClient
* \param[in] layerId Id of layer.
- * \param[in] Pposition pointer to an array where the position is stored.
+ * \param[in] pPosition pointer to an array where the position is stored.
* dimension[0]=x, dimension[1]=y
* \return ILM_TRUE if the method call was successful
* \return ILM_FAILED if the client can not call the method on the service.
* \param[in] width The original width of the surface
* \param[in] height The original height of the surface
* \param[in] pixelFormat The pixelformat to be used for the surface
- * \param[in/out] pSurfaceId
- * The value pSurfaceId points to is used as ID for new surface;
- * The ID of the newly created surface is returned in this parameter
+ * \param[in] pSurfaceId The value pSurfaceId points to is used as ID for new surface;
+ * \param[out] pSurfaceId The ID of the newly created surface is returned in this parameter
*
* \return ILM_TRUE if the method call was successful
* \return ILM_FAILED if the client can not call the method on the service.
/**
* \brief Create the logical surface, which has no native buffer associated
* \ingroup ilmClient
- * \param[in/out] pSurfaceId
- * The value pSurfaceId points to is used as ID for new surface;
- * The ID of the newly created surface is returned in this parameter
+ * \param[in] pSurfaceId The value pSurfaceId points to is used as ID for new surface;
+ * \param[out] pSurfaceId The ID of the newly created surface is returned in this parameter
* \return ILM_TRUE if the method call was successful
* \return ILM_FAILED if the client can not call the method on the service.
*/
/**
* @brief Set alpha value
- * @param alpha The new Alpha Value between 0.0 (full transparency) and 1.0 (fully visible)
+ * @param[in] newOpacity The new Alpha Value between 0.0 (full transparency) and 1.0 (fully visible)
*/
virtual void setOpacity(double newOpacity);
/**
* Set the visibility
- * @param visible set this object visible (true) or invisible (false)
+ * @param[in] newVisibility set this object visible (true) or invisible (false)
*/
virtual void setVisibility(bool newVisibility);
/**
* Assign custom shader for rendering
*
- * @param s Custom shader. If NULL, default shader will be used.
+ * @param[in] s Custom shader. If NULL, default shader will be used.
*/
void setShader(Shader* s);
virtual ~GraphicalSurface() {}
/**
- * Set Orientation value
- * @param orientation the new value. Multiples of 90 degrees. (0->0°, 1->90°, 2->180°,3->279°)
+ * @brief Set Orientation value
+ * @param[in] newOrientation the new value. Multiples of 90 degrees. (0->0°, 1->90°, 2->180°,3->279°)
*/
void setOrientation(OrientationType newOrientation);
OrientationType getOrientation() const;
/**
- * Set Source Viewport (only use portion of source graphics)
- * @param x Horizontal x position within source (clip from the left)
- * @param y Vertical y position within source (clip from the top)
- * @param width Width within source (can be used to clip from the right)
- * @param height Height within source (can be used to clip fromt he bottom)
+ * @brief Set Source Viewport (only use portion of source graphics)
+ * @param[in] newSource Rectangle defining position and size within surface (clip from the left)
*/
void setSourceRegion(const Rectangle& newSource);
/**
* Set Destination Viewport (Scale output)
- * @param x Horizontal x position of destination
- * @param y Vertical y position of destination
- * @param width Width of destination
- * @param height Height of destination
+ * @param[in] newDestination Rectangle defining destination position and size
*/
void setDestinationRegion(const Rectangle& newDestination);
Vector2 getDimension();
/**
- * @Description Indicate if a x,y position is inside the destination region.
- * Attention: Graphical Surface rotation is not yet supported.
+ * @brief Indicate if a x,y position is inside the destination region.
+ * Attention: Graphical Surface rotation is not yet supported.
* @param x_DestCoordinateSyst x position in the destination coordinate system
* @param y_DestCoordinateSyst y position in the destination coordinate system
* @return TRUE if the position is inside the destination region
bool isInside(unsigned int x_DestCoordinateSyst, unsigned int y_DestCoordinateSyst) const;
/**
- * @Description Transform a x,y position from destination coordinate system to
+ * @brief Transform a x,y position from destination coordinate system to
* source coordinate system. Attention, to get valid result the x,y
* positions given in parameter must be located within the destination
* region of the GraphicalSurface
*
- * @param x in/out : IN x position in the destination coordinate system
- * OUT x position in the source coordinate system
- * @param y in/out : IN y position in the destination coordinate system
- * OUT y position in the source coordinate system
+ * @param[in] x x position in the destination coordinate system
+ * @param[out] x x position in the source coordinate system
+ * @param[in] y y position in the destination coordinate system
+ * @param[out] y y position in the source coordinate system
* @param check If TRUE, a test will be done to make sure the x,y positions
* given in parameter are located within the destination region.
*
* \ingroup RendererAPI
* \param[in] fileToSave path to bitmap file to store the graphical content
* \param[in] id id of surface
+ * \param[in] layer_id id of layer
*/
virtual void doScreenShotOfSurface(std::string fileToSave, const unsigned int id, const unsigned int layer_id) = 0;
/**
* \brief default destructor
* \ingroup SceneAPI
- * \param[in]
- * \return
*/
virtual ~IScene() {}
/**
* \brief Remove a layer from the scene.
* \ingroup SceneAPI
- * \param[in] pointer to layer
+ * \param[in] layer pointer to layer
*/
virtual void removeLayer(Layer* layer) = 0;
/**
* \brief Remove surface from scene.
* \ingroup SceneAPI
- * \param[in] pointer to surface
+ * \param[in] surface pointer to surface
*/
virtual void removeSurface(Surface* surface) = 0;
public:
/**
* Creates a new shader instance by vertex and fragment shader name.
- * @param vertName File name of vertex shader.
- * @param fragName File name of fragment shader.
+ * @param vertFileName File name of vertex shader.
+ * @param fragFileName File name of fragment shader.
* @return new Shader instance, NULL if shader could not be loaded, compiled or linked.
*/
static Shader* createShader(const string& vertFileName, const string& fragFileName);
* Return a shader program from the gobal list. If no matching instance is found, a new
* one will be created and added to the list.
*
- * @param vertName File name of vertex shader.
- * @param fragName File name of fragment shader.
+ * @param vertFileName File name of vertex shader.
+ * @param fragFileName File name of fragment shader.
* @return new Program instance, NULL if shader could not be loaded, compiled or linked.
*/
static ShaderProgram* obtain(const string& vertFileName, const string& fragFileName);
* Protected constructor.
* New instances of this class are supposed to be created by the shader program factory.
*
- * @param vertName File name of vertex shader.
- * @param fragName File name of fragment shader.
+ * @param vertFileName File name of vertex shader.
+ * @param fragFileName File name of fragment shader.
*/
ShaderProgram(const string& vertFileName, const string& fragFileName);
/**
* Create a new shader program.
*
- * @param vertName File name of vertex shader.
- * @param fragName File name of fragment shader.
+ * @param vertFileName File name of vertex shader.
+ * @param fragFileName File name of fragment shader.
* @return new Program instance, NULL if program could not be created.
*/
static ShaderProgram* createProgram(const string& vertFileName, const string& fragFileName);
* "uSize 2f 1 2.5 1.25"
* "uTransform 4f 1 0 1.0 0.0 0.0 1.0 0.0 ..."
*
- * @param desc The description
+ * @param description The description
* @return Uniform object or NULL in case of a parse error
*/
static ShaderUniform* createFromStringDescription(const string& description);
*
* @param type Data type
* @param count Number of data elements
- * @param value Data values. Actual number of floats must be (count*(size of type)).
+ * @param values Data values. Actual number of floats must be (count*(size of type)).
* @param transpose Whether to transpose a matrix. Only needed if element type is a matrix.
*/
void setData(Type type, int count, const std::vector<float>& values, bool transpose = false);
}
/**
- * @Description:
+ * \brief:
* Return the first Surface located below a specific coordinate, and for which
* the opacity is above a certain level. Also translate the input coordinates
* which are display wide into surface wide coordinates.
* window. For this, we need to know to what is the layer / surface under the
* (x,y) mouse pointer.
*
- *
- *
- * @param x in/out : IN x position in the scene
- * OUT x position in the surface coordinate system
- * @param y in/out : IN y position in the scene
- * OUT y position in the surface coordinate system
- * @param minOpacity Minimal opacity that a surface should have to be elected
+ * @param[in] x x position in the scene
+ * @param[out] x x position in the surface coordinate system
+ * @param[in] y y position in the scene
+ * @param[out] y y position in the surface coordinate system
+ * @param[in] minOpacity Minimal opacity that a surface should have to be elected
*/
Surface* Scene::getSurfaceAt(unsigned int *x, unsigned int *y, double minOpacity)
{
--- /dev/null
+// This file defines the order of groups in the generated documentation
+
+/**
+ * \defgroup ServiceAPI Layer Management Service API
+ * \defgroup ilmClient Layer Management Client API
+ * \defgroup SceneAPI Layer Management Scene API
+ * \defgroup RendererAPI Layer Management Renderer API
+ * \defgroup CommunicatorAPI Layer Management Communicator API
+ * \defgroup Commands Layer Management Commands
+ */
The Layer Management Service is one of a number of components that have
been identified in the Graphics Framework Component Model. The components
that comprise the Graphics Framework are shown in the following diagram
-and summarised in the subsequent text.
+and summarized in the subsequent text.
\image html ./doc/images/overall_component_model.png Overall Component Model
\image latex ./doc/images/overall_component_model.png Overall Component Model
\li Load and instantiate Communication and Rendering packages to be used.
These will typically create own threads internally. It must be possible
to load these at runtime in order to have maximum flexibility.
-\li Call initialisation method on loaded packages
+\li Call initialization method on loaded packages
\li Call run method on loaded packages
\li Communication Packages will now typically wait for IPC Calls for creating
surfaces, layers etc and arranging themselves. Rendering packages will now
This section describes the Communication interface (Inter Process Communication)
between the Layer Management Service component and other components and external
systems. This is the interface for other applications to communicate with the
-Layer Management. This is used to control the Layer Management Service. Chapter
-8-12 describe internal programming interfaces and are only needed when extending
+Layer Management. This is used to control the Layer Management Service. \ref designOverview
+describes internal programming interfaces and is only needed when extending
the Layer Management Service with new communication mechanisms or renderers for
-new platforms. The IPC Message interfaces are described in terms of the
-connection, messages received and messages sent.
+new platforms. The IPC Message interfaces are described in \ref Commands.
\subsection componentInterfacesConnectionPolicy Connection Policy
as such can not be discussed here generically. The connection policy must be
described for each implementation of a communication package to be used.
-The following list of methods is generic and must always be implemented in
-communication packages, additional functionality can be provided be individual
-communication implementations though.
+The list of methods defined in \ref componentInterfacesCommands is generic and must
+always be implemented in communication packages, additional functionality can be
+provided be individual communication implementations though.
\subsection componentInterfacesCommands Commands
See \ref Commands.
-\section componentInterfacesNonFunctionalRequirements Non-Functional Requirements
+\section componentInterfacesRequirements Requirements
This section describes the non-functional requirements applicable to the Layer
Management Service Component. The requirements are split into two groups: those
directly met by the component and those where the component is supported by the
operational infrastructure.
-\subsection graphic01 Requirement Graphic01: 2D / 3D content simultaneously
+\subsection componentInterfacesNonFunctionalRequirements Non-Functional Requirements
+
+\subsubsection graphic01 Requirement Graphic01: 2D / 3D content simultaneously
The user wants to be able to arrange the view, e.g. in order to have a three
dimensional map on the left side and lane guidance information on the right
side.
-\subsection graphic02 Requirement Graphic02: Changing the application layout inside of a HMI system
+\subsubsection graphic02 Requirement Graphic02: Changing the application layout inside of a HMI system
The user wants to be able to change the layout of the displayed applications of
the HMI system. For example he sometimes wants to display In-Vehicle Information
other applications without losing menu content information provided by the HMI
System.
-\subsection graphic03 Requirement Graphic03: Display navigation information on a second display
+\subsubsection graphic03 Requirement Graphic03: Display navigation information on a second display
Rear seat passenger wants to see current navigation relevant information, like
map showing overview of current route, time and distance to destination and
more.
-\subsection graphic04 Requirement Graphic04: Making screenshot of head unit display
+\subsubsection graphic04 Requirement Graphic04: Making screenshot of head unit display
When performing evaluation of the system on bench or road test, tester might need to take
a screenshot of the actual screen content.
-\subsection graphic05 Requirement Graphic05: Showing Additional Information on Top
+\subsubsection graphic05 Requirement Graphic05: Showing Additional Information on Top
In some situations the user wants to display additional information on top of e.g. a map
provided by the navigation system. This information may include:
\li Speed limit information
\li On Screen Display Menu Information
-\subsection graphic06 Requirement Graphic06: Top of market experience while watching different application-content and additional information.
+\subsubsection graphic06 Requirement Graphic06: Top of market experience while watching different application-content and additional information.
Today's HMI systems have to be integrate different applications depending on the
end-user's need. Typical Applications are which have to be integrated are:
Therefore the user wants to have a top of market experience while watching and using application content and assistant information, without any disturbance (frame drop, unsmooth displayed animations, response delay on interaction) of the displayed content of the HMI system.
-\subsection graphic07 Requirement Graphic07: Using different application content
+\subsubsection graphic07 Requirement Graphic07: Using different application content
The needs of end-users regarding HMI systems can have a wide variety. Therefore they
range from only listening to audio and watching on board vehicle information to watching
The user wants to use these different applications on a HMI System in parallel.
-\subsection graphic08 Requirement Graphic08: Showing screen content of connected CE device
+\subsubsection graphic08 Requirement Graphic08: Showing screen content of connected CE device
User may want to connect smartphone device and see screen content of the
device on the head unit display.
Sound output of the connected device should be redirected thru car audio device,
input from the head unit should be redirected to the smartphone device.
-\section componentInterfacesRequiremetsOperationalInfrastructure Requirements placed on the Operational Infrastructure
+
+
+\subsection componentInterfacesRequiremetsOperationalInfrastructure Requirements placed on the Operational Infrastructure
\li Access to graphical content of applications managed by the Window Management API.
*/
“PlatformSurface” type with can store platform dependant data for renderers
(Window handles for example).
-"UML sequence example" diagram shows an exemplary sequence of actions. The layermanager
+"UML sequence example" diagram shows an exemplary sequence of actions. The LayerManagement
control is started, which in turn creates a communicator and starts it. A management
application is run and creates an initial layer, for example for third party
applications. The management applications then – at a later point in time – receives an
The Layer Management can be used in two scenarios:
-\section scenarioA Scenario A: All applications talk to the Layer Management themselves and configure their output.
+\section scenarioA Scenario A: LayerManagement without Central Control Instance
+
+This scenario uses no master to control the LayerManagement setup.
+All applications talk to the Layer Management themselves and configure their output.
Course of events:
\li (5) Layermanager returns the newly created surface identifier
\li (6) Application uses this identifier to set properties of its surface
-\section scenarioB Scenario B: A central control instances decides if applications are shown and where
+\section scenarioB Scenario B: LayerManagement with Central Control Instance
+
+A central control instances sets up the LayerManagement configuration.
+It has full control, which applications are shown and the way they are rendered.
\image html ./doc/images/with_central_control_instance.png Example with Central Control Instance
\image latex ./doc/images/with_central_control_instance.png Example with Central Control Instance
The Layer Management Service is composed of the following packages:
\li Layer Management
-\li One or more Renderer packages
+\li One Renderer package
\li One or more Communication packages
The Layer Management Service component makes use of the following external packages provided by the application framework:
\image html ./doc/images/layer_management_package_interaction.png Layer Management Package Interaction
\image latex ./doc/images/layer_management_package_interaction.png Layer Management Package Interaction
-The diagram below shows dependencies to all software components used by the LayerManager (DL = Dynamic Linking):
+The diagram below shows dependencies to all software components used by the LayerManager:
-\image html ./doc/images/layer_management_package_dependencies.png Layer Management Package Dependencies
-\image latex ./doc/images/layer_management_package_dependencies.png Layer Management Package Dependencies
+\image html ./doc/images/layer_management_package_dependencies.png Layer Management Package Dependencies (DL = Dynamic Linking)
+\image latex ./doc/images/layer_management_package_dependencies.png Layer Management Package Dependencies (DL = Dynamic Linking)
*/
\subsection layerManagementServiceDescription Description
The control is responsible for loading communication and renderer packages to be used. The
-control initiates the main singleton class, which in turn contains and manages the lists
-of layers and their surfaces through the layerlist object, and the list of logical groups.
+control initiates the main class, which in turn contains and manages the scene with the list
+of layers and their surfaces through the Scene object, and the list of logical groups.
The renderer packages are given access to these lists by the control and the communication
packages must be able to obtain information about properties requested by clients (e.g.
“SurfaceGetVisibility”).
\section scenePackageOverview Overview
-\image html ./doc/images/class_diagram_internal_container_types.png Class Diagram of Internal Container Types
-\image latex ./doc/images/class_diagram_internal_container_types.png Class Diagram of Internal Container Types
-
-\section scenePackageDescription Description
-
-The layerlist is an entity for managing the list of layers, their surfaces and the
+The scene is an entity for managing the list of layers, their surfaces and the
respective properties. It is passed to the render packages so it can be used to
iterate through the layers and surfaces and render these in the required render
order.
+\image html ./doc/images/class_diagram_internal_container_types.png Class Diagram of Internal Container Types
+\image latex ./doc/images/class_diagram_internal_container_types.png Class Diagram of Internal Container Types
+
+
\section scenePackagePublicInterface Public Interface
See \ref SceneAPI.
dependencies towards certain ways of communication and the usage of specific
communication libraries can be decided at runtime.
+On the client side it is recommended to use the \ref ilmClient for communication
+with the LayerManagerService, or to be more precise, with the loaded Communicator Plugin
+of the LayerManagerService.
+The LayerManagment client library implements an abstraction layer hiding the technical
+details of the underlying communication technology.
+This enables client applications to be used with different communication technologies
+implemented in LayerManager Communicator plugins.
+
+\image html ./images/layer_management_communicator_structure.png Layer Manager Communicator Structure
+\image latex ./images/layer_management_communicator_structure.png Layer Manager Communicator Structure
+
The general procedure for communicators is to establish their specific communication
(IPC, proprietary method, specific bus etc) and provide the message interface described
in chapter 6. When receiving commands on this communication channel the package builds
In order to be loadable by the layermanager, the created shared library must provide
both of these functions.
+This component is to be provided by the platform supplier.
+
+The GENIVI Consortium does not mandate any specific implementation. The only constraint
+is that the proposed solution needs to fulfill the API specification. Furthermore each
+Communicator Implementation has to provide a C-API for the Client applications (like HMI,
+Browser, Navigation) to hide the used InterProcessCommunication scheme.
+
\section communicationsPackageExample Example: Create the communication library “MyCommunicator”
(1) Create the class MyCommunicator, which inherits BaseCommunicator
See \ref CommunicatorAPI.
+\section communicationsPackageClientInterface Client Interface
+
+See \ref ilmClient.
+
\section communicationsPackageCommandObjectReference Command Object Reference
See \ref Commands.
rendering libraries. These are typically device dependant because of possible
dependencies on graphics hardware or displays for example.
-A typical implementation of a renderer will use the pointer to the layerlist given
+A typical implementation of a renderer will use the pointer to the scene given
in the constructor to access the list of current layers and their respective
-surfaces. In its own thread it will use the information in the layerlist to render
+surfaces. In its own thread it will use the information in the scene to render
its content. In most cases the renderer will need specific platform information for
each surface in order to access the actual graphical content of the platform (e.g.
native window handles or memory addresses). For this reason a renderer can append
The Layer Management service consists of platform independent
and platform dependent components. On each platform a separate
renderer and if required a separate communicator have to be
-implemented. The GENIVI proof of concept implementation uses for
-the communicator a d-bus interface and for the renderer an X11
+implemented. The GENIVI reference implementation uses for
+the communicator a DBUS interface and for the reference renderer an X11
renderer which is using X-Composite and X-Damage to access the
content of different applications. For the compositing itself the
glx extension GLX_EXT_Texture_from_pixmap and the blending mode
-of Open GL are used.
+of OpenGL/OpenGL ES are used.
*/
then given to the renderer under test and then checking for the desired output of
the renderer (positioning, overlapping, transparency etc).
-The implementation of the Layerlist can also be tested by automatic tests,
+The implementation of the Scene can also be tested by automatic tests,
inserting new layers, groups and surfaces, then changing properties and comparing
the results of subsequent calls to getter methods with the desired values.
dependence on a specific platform for rendering and window management.
The division of the Layer Management Service addresses this problem by
having separate rendering packages for each target platform. The
-communication packages, main program and layerlist are not platform
+communication packages, main program and scene are not platform
dependant. For maximum flexibility the communication and rendering
packages must not be known at compile time of the rest of the Layer
Management, i.e. they are loaded at runtime and integrated using a
\section assumptions Assumptions
-The Window Management API in use must provide a means for the rendering
-package to access the graphical content of individual applications.
+The Window Management API in use must provide access to the graphical
+content of individual applications for the rendering package.
*/
\vspace{0.3cm}
{\Large Component Design for $projectname}\\
\vspace{0.3cm}
-{\large Version 2.0 draft}\\
+{\large Version 2.0}\\
\vspace{0.3cm}
-{\small $date}\\
+{\small 06.02.2012}\\
\end{center}
{\large Sponsored by:}\\
\hline
13.04.2011 & 1.3 & Added Requirements tracebility, improved architecture figures and API improvements \\
\hline
-31.01.2012 & 2.0 draft & Updated API References to LayerManagement v0.9.5, switched to auto-generation of document \\
+06.02.2012 & 2.0 & Updated API References to LayerManagement v0.9.5, updated images, switched to auto-generation of document \\
\hline
\end{tabular}
projects / profile / ivi / layer-management.git / commitdiff
