Mercurial > pub > dyncall > bindings
comparison R/rdyncall/man/dynport.Rd @ 0:0cfcc391201f
initial from svn dyncall-1745
| author | Daniel Adler |
|---|---|
| date | Thu, 19 Mar 2015 22:26:28 +0100 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| -1:000000000000 | 0:0cfcc391201f |
|---|---|
| 1 \name{dynport} | |
| 2 \alias{dynport} | |
| 3 \alias{loadDynportNamespace} | |
| 4 \title{Dynamic R Bindings to standard and common C libraries} | |
| 5 \description{Function to bind APIs of standard and common C libraries to R via dynamically created interface environment objects | |
| 6 comprising R wrappers for C functions, object-like macros, enums and data types. | |
| 7 } | |
| 8 \usage{ | |
| 9 dynport(portname, portfile=NULL, | |
| 10 repo=system.file("dynports",package="rdyncall") ) | |
| 11 } | |
| 12 \arguments{ | |
| 13 \item{portname}{the name of a dynport, given as a literal or character string.} | |
| 14 \item{portfile}{\code{NULL} or character string giving a script file to parse ; \code{portname} and \code{repo} are .} | |
| 15 \item{repo}{character string giving the path to the root of the \emph{dynport} repository.} | |
| 16 } | |
| 17 \details{ | |
| 18 \code{dynport} offers a convenient method for binding entire C libraries to R. | |
| 19 This mechanism runs cross-platform and uses dynamic linkage but it implies | |
| 20 that the run-time library of a choosen binding need to be preinstalled in the system. | |
| 21 Depending on the OS, the run-time libraries may be preinstalled or require manual installation. | |
| 22 See \link{rdyncall-demos} for OS-specific installation notes for several C libraries. | |
| 23 | |
| 24 The binding method is data-driven using platform-portable specifications named \emph{DynPort} files. | |
| 25 DynPort files are stored in a repository that is installed as part of the package installation. | |
| 26 When \code{dynport} processes a \emph{DynPort} file given by \code{portname}, | |
| 27 an environment object is created, populated with R wrapper and helper objects | |
| 28 that make up the interface to the C library, and attached to the search path with the name \code{dynport:<PORTNAME>}. | |
| 29 Unloading of previously loaded dynport environments is achieved via \code{detach(dynport:<PORTNAME>)}. | |
| 30 | |
| 31 Up to \pkg{rdyncall} version 0.7.4, R name space objects were used as containers as described in the article \emph{Foreign Library Interface}, thus | |
| 32 dynport \sQuote{packages} appeared as \code{"package:<PORTNAME>"} on the search path. The mechanism to create synthesized R packages at run-time | |
| 33 required the use of \code{.Internal} calls. | |
| 34 But since the use of internal R functions is not permitted for packages distributed on CRAN we downgraded the package to use ordinary environment | |
| 35 objects starting with version 0.7.5 until a public interface for the creation of R namespace objects is available. | |
| 36 | |
| 37 The following gives a list of currently available \emph{DynPorts}: | |
| 38 \tabular{ll}{ | |
| 39 \strong{DynPort name/C Library} \tab \strong{Description} \cr | |
| 40 \code{expat} \tab Expat XML Parser Library \cr | |
| 41 \code{GL} \tab OpenGL 1.1 API \cr | |
| 42 \code{GLU} \tab OpenGL Utility Library \cr | |
| 43 \code{GLUT} \tab OpenGL Utility Toolkit Library \cr | |
| 44 \code{SDL} \tab Simple DirectMedia Layer library \cr | |
| 45 \code{SDL_image} \tab Loading of image files (png,jpeg..) \cr | |
| 46 \code{SDL_mixer} \tab Loading/Playing of ogg/mp3/mod music files. \cr | |
| 47 \code{SDL_ttf} \tab Loading/Rendering of True Type Fonts. \cr | |
| 48 \code{SDL_net} \tab Networking library. \cr | |
| 49 \code{glew} \tab OpenGL Extension Wrangler (includes OpenGL 3.0) \cr | |
| 50 \code{glfw} \tab OpenGL Windowing/Setup Library \cr | |
| 51 \code{gl3} \tab strict OpenGL 3 (untested) \cr | |
| 52 \code{R} \tab R shared library \cr | |
| 53 \code{ode} \tab Open Dynamics (Physics-) Engine (untested) \cr | |
| 54 \code{cuda} \tab NVIDIA Cuda (untested) \cr | |
| 55 \code{csound} \tab Sound programming language and library \cr | |
| 56 \code{opencl} \tab OpenCL (untested) \cr | |
| 57 \code{stdio} \tab C Standard Library I/O Functions \cr | |
| 58 \code{glpk} \tab GNU Linear Programming Kit \cr | |
| 59 \code{EGL} \tab Embedded Systems Graphics Library \cr | |
| 60 } | |
| 61 | |
| 62 As of the current implementation \emph{DynPort} files are R scripts | |
| 63 that perform up to three tasks: | |
| 64 | |
| 65 \itemize{ | |
| 66 \item Functions (and pointer-to-function variables) are mapped via \code{\link{dynbind}} and a description of the C library using a \emph{library signatures}. | |
| 67 \item Symbolic names are assigned to its values for object-like macro defines and C enum types. | |
| 68 \item Run-time type-information objects for aggregate C data types (struct and union) are registered via \code{\link{parseStructInfos}} and \code{\link{parseUnionInfos}}. | |
| 69 } | |
| 70 | |
| 71 The file path to the \emph{DynPort} file is derived from | |
| 72 \code{portname} per default. This would refer to \code{"<repo>/<portname>.R"} | |
| 73 where \code{repo} usually refers to the initial \emph{DynPort} repository | |
| 74 located at the sub-folder \code{"dynports/"} of the package. | |
| 75 If \code{portfile} is given, then this value is taken as file path (usually | |
| 76 for testing purpose). | |
| 77 | |
| 78 A tool suite, comprising AWK (was boost wave), GCC Preprocessor, GCC-XML and XSLT, was used to generate the available \emph{DynPort} files automatically | |
| 79 by extracting type information from C library header files. | |
| 80 | |
| 81 In a future release, the DynPort format will be changed to | |
| 82 a language-neutral text file document. For the interested reader: | |
| 83 A first prototyp is currently available in an FFI extension to the Lua | |
| 84 programming language (see \code{luadyncall} subversion sub-tree). | |
| 85 A third revision (including function types in call signatures, bitfields, arrays, etc..) | |
| 86 is currently in development. | |
| 87 } | |
| 88 \references{ | |
| 89 Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012. | |
| 90 \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf} | |
| 91 | |
| 92 Adler, D., Philipp, T. (2008) \emph{DynCall Project}. \url{http://dyncall.org} | |
| 93 | |
| 94 Clark, J. (1998). expat - XML Parser Toolkit. \url{http://expat.sourceforge.net} | |
| 95 | |
| 96 Ikits, M. and Magallon, M. (2002). The OpenGL Extension Wrangler Library. \url{http://glew.sourceforge.net} | |
| 97 | |
| 98 Latinga, S. (1998). The Simple DirectMedia Layer Library. \url{http://www.libsdl.org} | |
| 99 | |
| 100 Segal, M. and Akeley, K. (1992). The OpenGL Graphics System. A Specification, Version 1.0. \url{http://www.opengl.org} | |
| 101 | |
| 102 Smith, R. (2001). Open Dynamics Engine. \url{http://www.ode.org} | |
| 103 } | |
| 104 \examples{ | |
| 105 \donttest{ | |
| 106 # Using SDL and OpenGL in R | |
| 107 dynport(SDL) | |
| 108 dynport(GL) | |
| 109 # Initialize Video Sub-system | |
| 110 SDL_Init(SDL_INIT_VIDEO) | |
| 111 # Initialize Screen with OpenGL Context and Double Buffering | |
| 112 SDL_SetVideoMode(320,256,32,SDL_OPENGL+SDL_DOUBLEBUF) | |
| 113 # Clear Color and Clear Screen | |
| 114 glClearColor(0,0,1,0) # blue | |
| 115 glClear(GL_COLOR_BUFFER_BIT) | |
| 116 # Flip Double-Buffer | |
| 117 SDL_GL_SwapBuffers() | |
| 118 } | |
| 119 } | |
| 120 \keyword{programming} | |
| 121 \keyword{interface} | |
| 122 |