--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/R/rdyncall/man/rdyncall.Rd	Thu Mar 19 22:26:28 2015 +0100
@@ -0,0 +1,161 @@
+\name{rdyncall}
+\docType{package}
+\alias{rdyncall}
+\alias{rdyncall-package}
+\title{Improved Foreign Function Interface (FFI) and Dynamic Bindings to C Libraries (e.g. OpenGL) }
+\description{The package provides a cross-platform framework for dynamic binding of 
+  C libraries using a flexible Foreign Function Interface (FFI).
+  The FFI supports almost all fundamental C types, multiple calling conventions, 
+  symbolic access to foreign C struct/union data types and wrapping of R functions 
+  as C callback function pointers. 
+  Dynamic bindings to shared C libraries are data-driven by cross-platform binding specification 
+  using a compact plain text format ; an initial repository of bindings to a couple of 
+  common C libraries (OpenGL, SDL, Expat, glew, CUDA, OpenCL, ODE, R) comes with the package.
+  The package includes a variety of technology demos and OS-specific notes for installation of shared libraries.
+}
+\details{
+\pkg{rdyncall} offers a stack of interoperability technologies for working
+with foreign compiled languages using cross-platform portable abstraction
+methods. 
+
+For R application development, the package facilitates direct access from R
+to the C Application Programming Interface (API) of common libraries.
+This enables a new style of development: R applications can use
+low-level services of portable C libraries. 
+System-level code can be implemented in R without leaving the language.
+C APIs can be explored from within the R interpreter.
+Moving the R code from one platform to the other does not involve
+recompilation.
+Ofcourse, the run-time libraries need to be installed using a standard
+procedure of the target Operating-System Distribution. 
+See \link{rdyncall-demos} for details on this.
+
+For R core development and research, the package provides an improved Foreign 
+Function Interface (FFI) that can be used to call arbitrary 
+foreign precompiled C code without the need for additional 
+compilation of wrapper code. The back-end library is extendable with new
+calling conventions (such as Fortran,Pascal,COM,etc.. - which has not been 
+the focus as of this release, but might be supported officially in the near 
+futurue).
+Basic type-safety checks for argument passing and framework support for
+working with foreign C data types such as pointers, arrays, structs and 
+wrapping of R functions into first-level C callback function pointers
+round up this framework.
+}
+\section{Overview}{
+\itemize{
+\item Flexible FFI with support for almost all C types, type-safety checks and multiple calling conventions. See \code{\link{.dyncall}}.
+\item Loading of shared libraries with \emph{automatic unload management} and using direct access to OS linker. See \code{\link{.dynload}}.
+\item Cross-platform naming and loading of shared libraries. See \code{\link{dynfind}}.
+\item Binding C library functions via thin call wrappers. See \code{\link{dynbind}}.
+\item Handling of foreign C pointer, array and struct/union data types. See \code{\link{packing}} and \code{\link{struct}}.
+\item Dynamic wrapping of R functions as C function pointers to be used in C callbacks. See \code{\link{new.callback}}. 
+\item Dynamic bindings to standard and common C libraries and APIs (functions, variables, macro constants, enums, struct and union types). See \code{\link{dynport}}. 
+}
+}
+\section{Getting Started}{
+Several demos ranging from simple FFI calls to the C standard math library up to more complex 3D OpenGL/SDL Applications are available. 
+See \code{demos(package="rdyncall")} for an overview.
+Some demos require shared C libraries to be installed in the system. Please read \link{rdyncall-demos} for details.
+}
+\section{Supported Platforms}{
+The low-level implementation is mainly based on libraries from the DynCall 
+Project (\url{http://dyncall.org}). The library suite is distributed
+as part of the package source tree.
+
+The dyncall and dyncallback libraries implement generic low-level services
+with the help of a small amount of hand-written assembly code and
+careful modeling of the target machine's calling sequence
+for each platform to support.
+
+As of version 0.6, the following processor architectures are supported:
+
+\itemize{
+\item Intel i386 32-bit and AMD 64-bit Platforms
+\item ARM 32-bit (OABI, EABI and ARMHF ABI with support for Thumb)
+\item PowerPC 32-bit (support for callbacks not implemented for Linux/BSD)
+\item MIPS 32- and 64-bit (support for callbacks not yet implemented)
+\item SPARC 32- and 64-bit (support for callbacks not yet implemented)
+}
+
+The DynCall libraries are tested on Linux, Mac OS X, Windows, BSD derivates
+and more exotic platforms such as game consoles and Plan9.
+Please see the details on portability for \link{dyncall}, \link{dyncallback} and \link{dynload}
+and the official DynCall manual for full details of the back-end.
+The R Package has been tested on several major R platforms.
+The following gives a list of comments on platforms about the status of this package.
+
+\tabular{l}{
+\cr
+Linux Debian 4/ppc32 , R-2.4.0 : ok, but no callbacks. \cr
+Linux Debian 5/arm   , R-2.7.0 : ok, SDL not tested. \cr
+Linux Debian 6/x86   , R-2.12.2: ok. \cr
+Linux Debian 6/x64   , R-2.12.2: ok. \cr
+Linux Ubuntu 10/armv7, R-2.14  : ok. \cr
+Linux Fedora 14/x86            : ok. \cr
+Linux Ubuntu 12/i386 , R-2.15.1: ok. \cr
+Mac OS X 10.4/ppc    , R-2.10.0: ok. \cr
+Mac OS X 10.6/x86    , R-2.12.2: ok. \cr
+Mac OS X 10.6/x64    , R-2.12.2: ok. \cr
+Mac OS X 10.7/x64    , R-2.15.1: ok. \cr
+NetBSD 5.0/x86                 : ok.  \cr
+NetBSD 5.1/x64                 : ok.  \cr
+OpenBSD 4.8/x64      , R-2.7.0 : SDL failed. \cr
+Windows XP/x86       , R-2.12.2: ok. \cr
+Windows  7/x86       , R-2.12.2: ok. \cr
+Windows  7/x64       , R-2.12.2: ok, use correct 64-bit SDL DLL, SDL extension not tested - see \link{rdyncall-demos}) \cr
+FreeBSD 8.2/x86                : build ok, no tests made for X11. \cr
+}
+}
+\references{
+  Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012.
+  \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf}
+  
+  Adler, D., Philipp, T. (2008) \emph{DynCall Project}. 
+  \url{http://dyncall.org}
+}
+\examples{
+\donttest{
+# multimedia example
+# load dynports for OpenGL, Simple DirectMedia library
+# globals:
+surface <- NULL
+# init SDL and OpenGL
+init <- function()
+{
+  dynport(SDL)
+  dynport(GL)
+  if ( SDL_Init(SDL_INIT_VIDEO) != 0 ) stop("SDL_Init failed")
+  surface <<- SDL_SetVideoMode(320,240,32,SDL_DOUBLEBUF+SDL_OPENGL)
+  cat("surface dimension:", surface$w, "x",surface$h,sep="")
+}
+# draw blue screen
+updateSurface <- function(t)
+{
+  glClearColor(0,0,t \%\% 1,0)
+  glClear(GL_COLOR_BUFFER_BIT+GL_DEPTH_BUFFER_BIT)
+  SDL_GL_SwapBuffers()
+}
+# wait till close
+mainloop <- function()
+{
+  quit <- FALSE
+  evt <- new.struct(SDL_Event)
+  base <- SDL_GetTicks() / 1000
+  t <- 0
+  while(!quit) {
+    updateSurface(t)
+    while(SDL_PollEvent(evt)) {
+      if ( evt$type == SDL_QUIT ) quit <- TRUE
+    }
+    now <- SDL_GetTicks() / 1000
+    t <- now - base
+  }
+}
+init()
+mainloop()
+}
+}
+\keyword{programming}
+\keyword{interface}
+