dynport: Dynamic R Bindings to standard and common C libraries

In rdyncall: Improved Foreign Function Interface (FFI) and Dynamic Bindings to C Libraries (e.g. OpenGL)

Description

Function to bind APIs of standard and common C libraries to R via dynamically created interface environment objects comprising R wrappers for C functions, object-like macros, enums and data types.

Usage

dynport(portname, portfile=NULL,
 repo=system.file("dynports",package="rdyncall") )

Arguments

portname	the name of a dynport, given as a literal or character string.
portfile	NULL or character string giving a script file to parse ; portname and repo are .
repo	character string giving the path to the root of the dynport repository.

Details

dynport offers a convenient method for binding entire C libraries to R. This mechanism runs cross-platform and uses dynamic linkage but it implies that the run-time library of a choosen binding need to be preinstalled in the system. Depending on the OS, the run-time libraries may be preinstalled or require manual installation. See rdyncall-demos for OS-specific installation notes for several C libraries.

The binding method is data-driven using platform-portable specifications named DynPort files. DynPort files are stored in a repository that is installed as part of the package installation. When dynport processes a DynPort file given by portname, an environment object is created, populated with R wrapper and helper objects that make up the interface to the C library, and attached to the search path with the name dynport:<PORTNAME>. Unloading of previously loaded dynport environments is achieved via detach(dynport:<PORTNAME>).

Up to rdyncall version 0.7.4, R name space objects were used as containers as described in the article Foreign Library Interface, thus dynport ‘packages’ appeared as "package:<PORTNAME>" on the search path. The mechanism to create synthesized R packages at run-time required the use of .Internal calls. But since the use of internal R functions is not permitted for packages distributed on CRAN we downgraded the package to use ordinary environment objects starting with version 0.7.5 until a public interface for the creation of R namespace objects is available.

The following gives a list of currently available DynPorts:

DynPort name/C Library	Description
expat	Expat XML Parser Library
GL	OpenGL 1.1 API
GLU	OpenGL Utility Library
GLUT	OpenGL Utility Toolkit Library
SDL	Simple DirectMedia Layer library
SDL_image	Loading of image files (png,jpeg..)
SDL_mixer	Loading/Playing of ogg/mp3/mod music files.
SDL_ttf	Loading/Rendering of True Type Fonts.
SDL_net	Networking library.
glew	OpenGL Extension Wrangler (includes OpenGL 3.0)
glfw	OpenGL Windowing/Setup Library
gl3	strict OpenGL 3 (untested)
R	R shared library
ode	Open Dynamics (Physics-) Engine (untested)
cuda	NVIDIA Cuda (untested)
csound	Sound programming language and library
opencl	OpenCL (untested)
stdio	C Standard Library I/O Functions
glpk	GNU Linear Programming Kit
EGL	Embedded Systems Graphics Library

As of the current implementation DynPort files are R scripts that perform up to three tasks:

• Functions (and pointer-to-function variables) are mapped via dynbind and a description of the C library using a library signatures.

• Symbolic names are assigned to its values for object-like macro defines and C enum types.

• Run-time type-information objects for aggregate C data types (struct and union) are registered via parseStructInfos and parseUnionInfos.

The file path to the DynPort file is derived from portname per default. This would refer to "<repo>/<portname>.R" where repo usually refers to the initial DynPort repository located at the sub-folder "dynports/" of the package. If portfile is given, then this value is taken as file path (usually for testing purpose).

A tool suite, comprising AWK (was boost wave), GCC Preprocessor, GCC-XML and XSLT, was used to generate the available DynPort files automatically by extracting type information from C library header files.

In a future release, the DynPort format will be changed to a language-neutral text file document. For the interested reader: A first prototyp is currently available in an FFI extension to the Lua programming language (see luadyncall subversion sub-tree). A third revision (including function types in call signatures, bitfields, arrays, etc..) is currently in development.

References

Adler, D. (2012) “Foreign Library Interface”, The R Journal, 4(1), 30–40, June 2012. http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf

Adler, D., Philipp, T. (2008) DynCall Project. http://dyncall.org

Clark, J. (1998). expat - XML Parser Toolkit. http://expat.sourceforge.net

Ikits, M. and Magallon, M. (2002). The OpenGL Extension Wrangler Library. http://glew.sourceforge.net

Latinga, S. (1998). The Simple DirectMedia Layer Library. http://www.libsdl.org

Segal, M. and Akeley, K. (1992). The OpenGL Graphics System. A Specification, Version 1.0. http://www.opengl.org

Smith, R. (2001). Open Dynamics Engine. http://www.ode.org

Examples

# Using SDL and OpenGL in R 
dynport(SDL)
dynport(GL)
# Initialize Video Sub-system
SDL_Init(SDL_INIT_VIDEO)
# Initialize Screen with OpenGL Context and Double Buffering
SDL_SetVideoMode(320,256,32,SDL_OPENGL+SDL_DOUBLEBUF)
# Clear Color and Clear Screen
glClearColor(0,0,1,0) # blue
glClear(GL_COLOR_BUFFER_BIT)
# Flip Double-Buffer
SDL_GL_SwapBuffers()

rdyncall documentation built on May 2, 2019, 6:15 p.m.