Skip to content

Improved compile time errors #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cgphilipp wants to merge 10 commits into
base: master
Choose a base branch
from
Open

Improved compile time errors #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8cb7587
compile errors and tests: noise scope (partly)
Feb 5, 2018
55db9bd
compile errors and tests: noise done, sample scope (partly)
Feb 12, 2018
b10b039
compile errors and tests: sample done, scale done
Feb 26, 2018
6f022cf
compile errors and tests: all done
Mar 5, 2018
8c19908
compile errors and tests: uncommented all tests
Mar 5, 2018
a0bc591
documentation block in header files of generalized methods
Mar 6, 2018
258c63e
autosave changes
Mar 6, 2018
b459b8c
minor changes
Mar 19, 2018
61c1618
documentation for AssertionMacros and slight changes to underlying im…
Mar 28, 2018
a8b8002
extended readme according to the new compile time error messages
Mar 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 20 additions & 18 deletions CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

#
#
# CMake options
#
#

# CMake version
cmake_minimum_required(VERSION 3.0 FATAL_ERROR)
Expand Down Expand Up @@ -30,9 +30,9 @@ set_policy(CMP0042 NEW) # ENABLE CMP0042: MACOSX_RPATH is enabled by default.
set_policy(CMP0063 NEW) # ENABLE CMP0063: Honor visibility properties for all target types.


#
#
# Project description and (meta) information
#
#

# Get git revision
get_git_head_revision(GIT_REFSPEC GIT_SHA1)
Expand All @@ -56,9 +56,9 @@ set(META_NAME_VERSION "${META_PROJECT_NAME} v${META_VERSION} (${META_VERS
set(META_CMAKE_INIT_SHA "6a6f30b38a1cee31ccac3f091816f28e0f6bce4b")


#
#
# Project configuration options
#
#

# Project options
option(OPTION_SELF_CONTAINED "Create a self-contained install with all dependencies." OFF)
Expand All @@ -68,17 +68,19 @@ option(OPTION_BUILD_EXAMPLES "Build examples."
option(OPTION_BUILD_TOOLS "Build tools." ON)


#
#
# Declare project
#
#

# Generate folders for IDE targets (e.g., VisualStudio solutions)
set_property(GLOBAL PROPERTY USE_FOLDERS ON)
set(IDE_FOLDER "")
set(IDE_FOLDER "")

# Declare project
project(${META_PROJECT_NAME} C CXX)

include(CTest)

# Set output directories
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
Expand All @@ -88,9 +90,9 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR})
file(WRITE "${PROJECT_BINARY_DIR}/VERSION" "${META_NAME_VERSION}")


#
#
# Compiler settings and options
#
#

include(cmake/CompileOptions.cmake)

Expand All @@ -107,9 +109,9 @@ enable_cppcheck(On)
enable_clang_tidy(On)


#
#
# Deployment/installation setup
#
#

# Get project name
set(project ${META_PROJECT_NAME})
Expand Down Expand Up @@ -161,23 +163,23 @@ if(NOT SYSTEM_DIR_INSTALL)
if(APPLE)
set(CMAKE_INSTALL_RPATH "@loader_path/../../../${INSTALL_LIB}")
else()
set(CMAKE_INSTALL_RPATH "$ORIGIN/${INSTALL_LIB}")
set(CMAKE_INSTALL_RPATH "$ORIGIN/${INSTALL_LIB}")
endif()
endif()


#
#
# Project modules
#
#

add_subdirectory(source)
add_subdirectory(docs)
add_subdirectory(deploy)


#
#
# Deployment (global project files)
#
#

# Install version file
install(FILES "${PROJECT_BINARY_DIR}/VERSION" DESTINATION ${INSTALL_ROOT} COMPONENT runtime)
Expand Down
259 changes: 162 additions & 97 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,162 @@
# glkernel
C++ library for pre-computing noise, and random sample-kernels.

## Project Health (master)

| Service | System | Compiler | Targets | Status |
| ------- | ------ | -------- | ------- | ------ |
| Jenkins | Ubuntu 14.04 | GCC 4.8 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-gcc4.8)](http://jenkins.hpi3d.de/job/glkernel-linux-gcc4.8)|
| Jenkins | Ubuntu 14.04 | GCC 4.9 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-gcc4.9)](http://jenkins.hpi3d.de/job/glkernel-linux-gcc4.9)|
| Jenkins | Ubuntu 14.04 | GCC 5.3 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-gcc5.3)](http://jenkins.hpi3d.de/job/glkernel-linux-gcc5.3)|
| Jenkins | Ubuntu 14.04 | Clang 3.5 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-clang3.5)](http://jenkins.hpi3d.de/job/glkernel-linux-clang3.5) |
| Jenkins | Windows 8.1 | MSVC 2013 Update 5 | all, test, install | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-windows-msvc2013)](http://jenkins.hpi3d.de/job/glkernel-windows-msvc2013) |
| Jenkins | Windows 8.1 | MSVC 2015 Update 1 | all, test, install | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-windows-msvc2015)](http://jenkins.hpi3d.de/job/glkernel-windows-msvc2015) |

## Features

ToDo

##### Feature

ToDo

## Using glkernel

ToDo

##### Dependencies

ToDo

##### Linking binaries

ToDo

##### glkernel-cmd

Additionally to using glkernel as a library, there is a standalone command line tool to generate kernels from JSON descriptions.
The usage is as follows: ```glkernel-cmd --i {input filename} --o {output filename}```, where ```{input filename}``` is a JSON kernel description file and ```{output file}``` is a JSON file containing a kernel.

The description file must contain an entry "init-kernel" that describes the size and the number of components of the the kernel that will be generated.
It also has to contain an entry "commands", which is an array of commands that will be executed on the kernel.
For these, all glkernel commands can be used.

The naming convention for applying glkernel commands is ```"{namespace}.{function name}"```, e.g. ```"noise.uniform"``` for ```noise::uniform```.
Arguments can be passed as a JSON object, e.g. ```{ "noise.uniform": { "range_min": -1.0, "range_max": 1.0 } }``` will call ```noise::uniform(kernel, -1.0, 1.0)```.

Here is an input JSON for generating 4 samples using golden point set sampling, scaling them to [-0.5, 0.5] and shuffling them randomly:
```json
{
"init-kernel": {
"components": 2,
"width": 4,
"height": 1,
"depth": 1
},

"commands": [
{ "sample.golden_point_set": { } },
{ "scale.range": { "range_to_lower": -0.5, "range_to_upper": 0.5 } },
{ "shuffle.random": { } }
]
}
```

The generated output JSON will look like this:
```json
{
"kernel": [
[
[
[
-0.286392,
-0.437815
],
[
-0.140494,
0.180219
],
[
0.0955744,
-0.201747
],
[
0.47754,
0.416287
]
]
]
],
"size": {
"depth": 1,
"height": 1,
"width": 4
}
}

```
# glkernel
C++ library for pre-computing noise, and random sample-kernels.

## Project Health (master)

| Service | System | Compiler | Targets | Status |
| ------- | ------ | -------- | ------- | ------ |
| Jenkins | Ubuntu 14.04 | GCC 4.8 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-gcc4.8)](http://jenkins.hpi3d.de/job/glkernel-linux-gcc4.8)|
| Jenkins | Ubuntu 14.04 | GCC 4.9 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-gcc4.9)](http://jenkins.hpi3d.de/job/glkernel-linux-gcc4.9)|
| Jenkins | Ubuntu 14.04 | GCC 5.3 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-gcc5.3)](http://jenkins.hpi3d.de/job/glkernel-linux-gcc5.3)|
| Jenkins | Ubuntu 14.04 | Clang 3.5 | all, test | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-linux-clang3.5)](http://jenkins.hpi3d.de/job/glkernel-linux-clang3.5) |
| Jenkins | Windows 8.1 | MSVC 2013 Update 5 | all, test, install | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-windows-msvc2013)](http://jenkins.hpi3d.de/job/glkernel-windows-msvc2013) |
| Jenkins | Windows 8.1 | MSVC 2015 Update 1 | all, test, install | [![Build Status](http://jenkins.hpi3d.de/buildStatus/icon?job=glkernel-windows-msvc2015)](http://jenkins.hpi3d.de/job/glkernel-windows-msvc2015) |

## Features

* Smart template error messages

##### Smart template error messages

Most methods of glkernel operate a kernel as well as additional parameters. This may lead to a template argument mismatch if a method is called with arguments that do not match the intended signature.
These cases are caught by glkernel and a helpful compile time error message is provided to the developers.

## Using glkernel

Before using glkernel, it is important to get clear about the following three properties of a kernel:
* Dimension
* Cell type
* Component type

###### Dimension
Defines in how many dimensions a kernel extends. Can be compared to the dimension of a tensor.
The dimension is defined implicitly by the kernel's size, which is determined for each dimension.
A kernel of size `{4, 1, 2}` has the dimension _three_.

###### Cell type
The number of cells is determined by the kernel's size. In the example above, the kernel would contain eight cells. These cells can be of different cell types. However, the cell type must be homogeneous for the entire kernel. Cells can be of a scalar (_one_ component per cell) or of a vectorial (_two_, _three_ or _four_ components per cell) type.

###### Component type
The component type specifies of which type the values (= components) within a kernel are. Again, the component type must be homogeneous. This is most likely a matter of precision and `float` or `double` would be appropriate component types.


### As a library

##### Dependencies

Using glkernel requires a C++11 compatible compiler.
For linking against glkernel: `glm`
For multithreading support (optional): `OpenMP` for multithreading support
For building the glkernel tests: `cmake` Version 3.1 or newer

##### Linking

Glkernel is a header-only library, so linking is as simple as including the headers providing the needed functionality.
For flexibel kernel instantiation, you need to:
```cpp
#include <glm/vec2.hpp>
#include <glm/vec3.hpp>
#include <glm/vec4.hpp>
#include <glkernel/Kernel.h>
```
This allows the instantiation of kernels with scalar or vectorial cell types. Following this, a kernel can be used within methods of different namespaces each providing specific functionality. According to your purpose, you need to:
```cpp
#include <glkernel/noise.h> // Kernel generation based on noise
#include <glkernel/sample.h> // Kernel generation based on sampling
#include <glkernel/sequence.h> // Kernel generation based on regular sequences
#include <glkernel/scale.h> // Kernel transformation by range adjustments
#include <glkernel/shuffle.h> // Kernel transformation by shuffling of elements
#include <glkernel/sort.h> // Kernel transformation by sorting of elements
```


##### Usage
The following aliases are ___already defined by glkernel___ for comfortable usage:
```cpp
using kernel1 = tkernel<float>; // Cell type: scalar, Component type: float
using kernel2 = tkernel<glm::vec2>; // Cell type: vec2, Component type: float
using kernel3 = tkernel<glm::vec3>; // Cell type: vec3, Component type: float
using kernel4 = tkernel<glm::vec4>; // Cell type: vec4, Component type: float

using dkernel1 = tkernel<double>; // Cell type: scalar, Component type: double
using dkernel2 = tkernel<glm::dvec2>; // Cell type: vec2, Component type: double
using dkernel3 = tkernel<glm::dvec3>; // Cell type: vec3, Component type: double
using dkernel4 = tkernel<glm::dvec4>; // Cell type: vec4, Component type: double
```
As you can see from the aliases above, the __cell-__ and __component__ type are specified by the kernel class' template arguments. The __dimension__ must be specified during the instantiation.
The following snippet shows a basic order in which the glkernel library can be used:

```cpp
auto fkernel2 = glkernel::kernel2{4, 1, 1}; // Instantiate 3D float kernel with two components per cell
glkernel::sample::golden_point_set(fkernel2); // Generate 'golden point set'
glkernel::scale::range(fkernel2, -0.5f, 0.5f);) // Scale kernel to [-0.5, 0.5] in each dimension
glkernel::shuffle::random(fkernel2); // Shuffle elements randomly
```




### Via command line interface
###### glkernel-cmd

Additionally to using glkernel as a library, there is a standalone command line tool to generate kernels from JSON descriptions.
The usage is as follows: ```glkernel-cmd --i {input filename} --o {output filename}```, where ```{input filename}``` is a JSON kernel description file and ```{output file}``` is a JSON file containing a kernel.

The description file must contain an entry "init-kernel" that describes the size and the number of components of the the kernel that will be generated.
It also has to contain an entry "commands", which is an array of commands that will be executed on the kernel.
For these, all glkernel commands can be used.

The naming convention for applying glkernel commands is ```"{namespace}.{function name}"```, e.g. ```"noise.uniform"``` for ```noise::uniform```.
Arguments can be passed as a JSON object, e.g. ```{ "noise.uniform": { "range_min": -1.0, "range_max": 1.0 } }``` will call ```noise::uniform(kernel, -1.0, 1.0)```.

Here is an input JSON for generating 4 samples using golden point set sampling, scaling them to [-0.5, 0.5] and shuffling them randomly:
```json
{
"init-kernel": {
"components": 2,
"width": 4,
"height": 1,
"depth": 1
},

"commands": [
{ "sample.golden_point_set": { } },
{ "scale.range": { "range_to_lower": -0.5, "range_to_upper": 0.5 } },
{ "shuffle.random": { } }
]
}
```

The generated output JSON will look like this:
```json
{
"kernel": [
[
[
[
-0.286392,
-0.437815
],
[
-0.140494,
0.180219
],
[
0.0955744,
-0.201747
],
[
0.47754,
0.416287
]
]
]
],
"size": {
"depth": 1,
"height": 1,
"width": 4
}
}

```
Loading