|
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
|
