---
title: "C API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{C API}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(colorfast)
```

`{colorfast}` exports three C functions for use in other packages.

To use these functions:

* In your package `DESCRIPTION`
    * Add `LinkingTo: colorfast` 
    * Add `Depends: colorfast (>= 1.0.1)`
* In your C code
    * Add `#include <colorfast.h>`
    * Call the functions below

```
void col_to_rgb(const char *col, uint8_t ptr[4]);
uint32_t col_to_int(const char *col); 
void int_to_col(uint32_t icol, char buf[10]);
```


## String color to vector of RGBA values 

`void col_to_rgb(const char *col, uint8_t ptr[4])`

* `const char *col` is a pointer to a null-terminated C string containing
  either a hex color, or the name of a standard R color: E.g. `"#1287Af"`, 
  `"hotpink"`
* `uint8_t ptr[4]` holds the values returned from the function i.e. RGBA color
  component values

The R call `col_to_rgb('red')`, can be called via the C api as:

``` c
#include <stdint.h>
#include <colorfast.h>

void convert_col_to_rgb(const char *col) {
  uint8_t values[4];
  col_to_rgb(col, values);
  
  for (int i = 0; i < 4; ++i) {
    printf("%i ", values[i]);
  }
}
```


```{r echo=FALSE, eval=FALSE}

library(callme)
code = r"(
#include <stdint.h>
#include <colorfast.h>

void convert_col_to_rgb(const char *col) {
  uint8_t values[4];
  col_to_rgb(col, values);
  
  for (int i = 0; i < 4; ++i) {
    printf("%i ", values[i]);
  }
}


SEXP test() {
  convert_col_to_rgb("red");
  return R_NilValue;
}
)"

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Find the location of nara.h and include its directory in the search path
# using C Pre-Processor flags (PKG_CPPFLAGS)
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
nara_h <- system.file("include", "colorfast.h", package = "colorfast", mustWork = TRUE)
cpp_include = paste0("-I", dirname(nara_h))
callme::compile(code, PKG_CPPFLAGS = cpp_include)


test()
```






## String color to packed integer color 

`void col_to_int(const char *col)`

* `const char *col` is a pointer to a null-terminated C string containing
  either a hex color, or the name of a standard R color: E.g. `"#1287Af"`, 
  `"hotpink"`

``` c
#include <stdint.h>
#include <colorfast.h>

void convert_col_to_int(const char *col) {
  uint32_t value = col_to_int(col);
  
  printf("%i ", value);
}
```


```{r echo=FALSE, eval=FALSE}

library(callme)
code = r"(
#include <stdint.h>
#include <colorfast.h>

void convert_col_to_int(const char *col) {
  uint32_t value = col_to_int(col);
  
  printf("%i ", value);
}


SEXP test() {
  convert_col_to_int("red");
  return R_NilValue;
}
)"

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Find the location of nara.h and include its directory in the search path
# using C Pre-Processor flags (PKG_CPPFLAGS)
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
nara_h <- system.file("include", "colorfast.h", package = "colorfast", mustWork = TRUE)
cpp_include = paste0("-I", dirname(nara_h))
callme::compile(code, PKG_CPPFLAGS = cpp_include)


test()
```


## Packed integer color to hexadecimal color

`void int_to_col(uint32_t icol, char buf[10])`

* `uint32_t icol` unsigned integer holding the 4 RGBA color values
* `char buf[10]` a character buffer into which the hex color will be written
   e.g. `#1154EE00`

``` c
#include <stdint.h>
#include <colorfast.h>

void convert_int_to_col(uint32_t icol) {
  char buf[10];
  int_to_col(icol, buf);
  
  printf("%s\n", buf);
}
```


```{r echo=FALSE, eval=FALSE}

library(callme)
code = r"(
#include <stdint.h>
#include <colorfast.h>

void convert_int_to_col(uint32_t icol) {
  char buf[10];
  int_to_col(icol, buf);
  
  printf("%s\n", buf);
}


SEXP test() {
  convert_int_to_col(123456);
  return R_NilValue;
}
)"

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Find the location of nara.h and include its directory in the search path
# using C Pre-Processor flags (PKG_CPPFLAGS)
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
nara_h <- system.file("include", "colorfast.h", package = "colorfast", mustWork = TRUE)
cpp_include = paste0("-I", dirname(nara_h))
callme::compile(code, PKG_CPPFLAGS = cpp_include)


test()
```