0
+ − 1 \name{rdyncall}
+ − 2 \docType{package}
+ − 3 \alias{rdyncall}
+ − 4 \alias{rdyncall-package}
+ − 5 \title{Improved Foreign Function Interface (FFI) and Dynamic Bindings to C Libraries (e.g. OpenGL) }
+ − 6 \description{The package provides a cross-platform framework for dynamic binding of
+ − 7 C libraries using a flexible Foreign Function Interface (FFI).
+ − 8 The FFI supports almost all fundamental C types, multiple calling conventions,
+ − 9 symbolic access to foreign C struct/union data types and wrapping of R functions
+ − 10 as C callback function pointers.
+ − 11 Dynamic bindings to shared C libraries are data-driven by cross-platform binding specification
+ − 12 using a compact plain text format ; an initial repository of bindings to a couple of
+ − 13 common C libraries (OpenGL, SDL, Expat, glew, CUDA, OpenCL, ODE, R) comes with the package.
+ − 14 The package includes a variety of technology demos and OS-specific notes for installation of shared libraries.
+ − 15 }
+ − 16 \details{
+ − 17 \pkg{rdyncall} offers a stack of interoperability technologies for working
+ − 18 with foreign compiled languages using cross-platform portable abstraction
+ − 19 methods.
+ − 20
+ − 21 For R application development, the package facilitates direct access from R
+ − 22 to the C Application Programming Interface (API) of common libraries.
+ − 23 This enables a new style of development: R applications can use
+ − 24 low-level services of portable C libraries.
+ − 25 System-level code can be implemented in R without leaving the language.
+ − 26 C APIs can be explored from within the R interpreter.
+ − 27 Moving the R code from one platform to the other does not involve
+ − 28 recompilation.
+ − 29 Ofcourse, the run-time libraries need to be installed using a standard
+ − 30 procedure of the target Operating-System Distribution.
+ − 31 See \link{rdyncall-demos} for details on this.
+ − 32
+ − 33 For R core development and research, the package provides an improved Foreign
+ − 34 Function Interface (FFI) that can be used to call arbitrary
+ − 35 foreign precompiled C code without the need for additional
+ − 36 compilation of wrapper code. The back-end library is extendable with new
+ − 37 calling conventions (such as Fortran,Pascal,COM,etc.. - which has not been
+ − 38 the focus as of this release, but might be supported officially in the near
+ − 39 futurue).
+ − 40 Basic type-safety checks for argument passing and framework support for
+ − 41 working with foreign C data types such as pointers, arrays, structs and
+ − 42 wrapping of R functions into first-level C callback function pointers
+ − 43 round up this framework.
+ − 44 }
+ − 45 \section{Overview}{
+ − 46 \itemize{
+ − 47 \item Flexible FFI with support for almost all C types, type-safety checks and multiple calling conventions. See \code{\link{.dyncall}}.
+ − 48 \item Loading of shared libraries with \emph{automatic unload management} and using direct access to OS linker. See \code{\link{.dynload}}.
+ − 49 \item Cross-platform naming and loading of shared libraries. See \code{\link{dynfind}}.
+ − 50 \item Binding C library functions via thin call wrappers. See \code{\link{dynbind}}.
+ − 51 \item Handling of foreign C pointer, array and struct/union data types. See \code{\link{packing}} and \code{\link{struct}}.
+ − 52 \item Dynamic wrapping of R functions as C function pointers to be used in C callbacks. See \code{\link{new.callback}}.
+ − 53 \item Dynamic bindings to standard and common C libraries and APIs (functions, variables, macro constants, enums, struct and union types). See \code{\link{dynport}}.
+ − 54 }
+ − 55 }
+ − 56 \section{Getting Started}{
+ − 57 Several demos ranging from simple FFI calls to the C standard math library up to more complex 3D OpenGL/SDL Applications are available.
+ − 58 See \code{demos(package="rdyncall")} for an overview.
+ − 59 Some demos require shared C libraries to be installed in the system. Please read \link{rdyncall-demos} for details.
+ − 60 }
+ − 61 \section{Supported Platforms}{
+ − 62 The low-level implementation is mainly based on libraries from the DynCall
+ − 63 Project (\url{http://dyncall.org}). The library suite is distributed
+ − 64 as part of the package source tree.
+ − 65
+ − 66 The dyncall and dyncallback libraries implement generic low-level services
+ − 67 with the help of a small amount of hand-written assembly code and
+ − 68 careful modeling of the target machine's calling sequence
+ − 69 for each platform to support.
+ − 70
+ − 71 As of version 0.6, the following processor architectures are supported:
+ − 72
+ − 73 \itemize{
+ − 74 \item Intel i386 32-bit and AMD 64-bit Platforms
+ − 75 \item ARM 32-bit (OABI, EABI and ARMHF ABI with support for Thumb)
+ − 76 \item PowerPC 32-bit (support for callbacks not implemented for Linux/BSD)
+ − 77 \item MIPS 32- and 64-bit (support for callbacks not yet implemented)
+ − 78 \item SPARC 32- and 64-bit (support for callbacks not yet implemented)
+ − 79 }
+ − 80
+ − 81 The DynCall libraries are tested on Linux, Mac OS X, Windows, BSD derivates
+ − 82 and more exotic platforms such as game consoles and Plan9.
+ − 83 Please see the details on portability for \link{dyncall}, \link{dyncallback} and \link{dynload}
+ − 84 and the official DynCall manual for full details of the back-end.
+ − 85 The R Package has been tested on several major R platforms.
+ − 86 The following gives a list of comments on platforms about the status of this package.
+ − 87
+ − 88 \tabular{l}{
+ − 89 \cr
+ − 90 Linux Debian 4/ppc32 , R-2.4.0 : ok, but no callbacks. \cr
+ − 91 Linux Debian 5/arm , R-2.7.0 : ok, SDL not tested. \cr
+ − 92 Linux Debian 6/x86 , R-2.12.2: ok. \cr
+ − 93 Linux Debian 6/x64 , R-2.12.2: ok. \cr
+ − 94 Linux Ubuntu 10/armv7, R-2.14 : ok. \cr
+ − 95 Linux Fedora 14/x86 : ok. \cr
+ − 96 Linux Ubuntu 12/i386 , R-2.15.1: ok. \cr
+ − 97 Mac OS X 10.4/ppc , R-2.10.0: ok. \cr
+ − 98 Mac OS X 10.6/x86 , R-2.12.2: ok. \cr
+ − 99 Mac OS X 10.6/x64 , R-2.12.2: ok. \cr
+ − 100 Mac OS X 10.7/x64 , R-2.15.1: ok. \cr
+ − 101 NetBSD 5.0/x86 : ok. \cr
+ − 102 NetBSD 5.1/x64 : ok. \cr
+ − 103 OpenBSD 4.8/x64 , R-2.7.0 : SDL failed. \cr
+ − 104 Windows XP/x86 , R-2.12.2: ok. \cr
+ − 105 Windows 7/x86 , R-2.12.2: ok. \cr
+ − 106 Windows 7/x64 , R-2.12.2: ok, use correct 64-bit SDL DLL, SDL extension not tested - see \link{rdyncall-demos}) \cr
+ − 107 FreeBSD 8.2/x86 : build ok, no tests made for X11. \cr
+ − 108 }
+ − 109 }
+ − 110 \references{
+ − 111 Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012.
+ − 112 \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf}
+ − 113
+ − 114 Adler, D., Philipp, T. (2008) \emph{DynCall Project}.
+ − 115 \url{http://dyncall.org}
+ − 116 }
+ − 117 \examples{
+ − 118 \donttest{
+ − 119 # multimedia example
+ − 120 # load dynports for OpenGL, Simple DirectMedia library
+ − 121 # globals:
+ − 122 surface <- NULL
+ − 123 # init SDL and OpenGL
+ − 124 init <- function()
+ − 125 {
+ − 126 dynport(SDL)
+ − 127 dynport(GL)
+ − 128 if ( SDL_Init(SDL_INIT_VIDEO) != 0 ) stop("SDL_Init failed")
+ − 129 surface <<- SDL_SetVideoMode(320,240,32,SDL_DOUBLEBUF+SDL_OPENGL)
+ − 130 cat("surface dimension:", surface$w, "x",surface$h,sep="")
+ − 131 }
+ − 132 # draw blue screen
+ − 133 updateSurface <- function(t)
+ − 134 {
+ − 135 glClearColor(0,0,t \%\% 1,0)
+ − 136 glClear(GL_COLOR_BUFFER_BIT+GL_DEPTH_BUFFER_BIT)
+ − 137 SDL_GL_SwapBuffers()
+ − 138 }
+ − 139 # wait till close
+ − 140 mainloop <- function()
+ − 141 {
+ − 142 quit <- FALSE
+ − 143 evt <- new.struct(SDL_Event)
+ − 144 base <- SDL_GetTicks() / 1000
+ − 145 t <- 0
+ − 146 while(!quit) {
+ − 147 updateSurface(t)
+ − 148 while(SDL_PollEvent(evt)) {
+ − 149 if ( evt$type == SDL_QUIT ) quit <- TRUE
+ − 150 }
+ − 151 now <- SDL_GetTicks() / 1000
+ − 152 t <- now - base
+ − 153 }
+ − 154 }
+ − 155 init()
+ − 156 mainloop()
+ − 157 }
+ − 158 }
+ − 159 \keyword{programming}
+ − 160 \keyword{interface}
+ − 161