Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/arkaht/cpp-curve-x

Curve-X ─ a small and easy-to-use C++ Bézier library to create 2D-splines with its own GUI editor.
https://github.com/arkaht/cpp-curve-x

bezier cmake cpp cpp11 cpp14 cpp17 cpp20 curve library spline

Last synced: 5 days ago
JSON representation

Curve-X ─ a small and easy-to-use C++ Bézier library to create 2D-splines with its own GUI editor.

Host: GitHub
URL: https://github.com/arkaht/cpp-curve-x
Owner: arkaht
License: mit
Created: 2024-04-24T15:53:20.000Z (5 months ago)
Default Branch: master
Last Pushed: 2024-05-22T20:02:40.000Z (4 months ago)
Last Synced: 2024-05-22T21:29:19.049Z (4 months ago)
Topics: bezier, cmake, cpp, cpp11, cpp14, cpp17, cpp20, curve, library, spline
Language: C++
Homepage: https://guthen.itch.io/curve-editor-x
Size: 64.5 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Curve-X
**Curve-X is a small and easy-to-use C++ Bézier library to create 2D-splines with its own GUI editor.**

*If you are a game developer working on your own C++ game or engine and you want to have fine control over your values (let's say: gamepad sensitivity, dynamic FOV depending on the player's speed, gravity force, particle effects, animations, etc.) for the sake of game feel, this project may interests you.*

Curve-X allows to create 2D-splines, either they are intended to be geometrical shapes or for timed-based values. It is simple of usage yet allows a lot of manipulation. The code is also well-documented: each class, functions and enums are properly described.

By default, the project is built for C++17, yet it is compatible with the versions specified in [Dependencies](#dependencies).

This project is still under development, feel free to raise [issues](https://github.com/arkaht/cpp-curve-x/issues) as you encounter them.

## Dependencies
+ C++11, 14, 17 or 20 compiler
+ CMake 3.11 is optional

## Features
+ **Carefully well-documented code for classes, functions and enums**
+ Written in **simple and straightforward C++17** using **snake_case** notation
+ Project IDE-independent thanks to **CMake**
+ **Custom [GUI editor](https://github.com/arkaht/cpp-curve-editor-x) to easily create and edit curve files**
+ Support for both geometrical shapes and timed-based curves
+ Multiple evaluation methods: progress (from 0.0 to 1.0), time (using X-axis) and distance.
+ **Embedded curves serialization and un-serialization methods**
+ Custom and human-readable text format for curves serialization
+ **Free and open-source**

![image](https://github.com/arkaht/cpp-curve-x/assets/114919245/a32a058e-9ba1-4add-89f0-de4ad0f14434)
> Two examples: a geometrical shape curve ([`samples/heart.cvx`](https://github.com/arkaht/cpp-curve-x/blob/master/samples/heart.cvx)) and a timed-based curve ([`samples/controller-gamepad-sensitivity.cvx`](https://github.com/arkaht/cpp-curve-x/blob/master/samples/controller-gamepad-sensitivity.cvx)) from the [GUI editor](https://github.com/arkaht/cpp-curve-editor-x)

## Project Structure
This project is split into two Github repositories: the library (this one) and the [GUI editor](https://github.com/arkaht/cpp-curve-editor-x). You are not forced to use the editor, it is entirely optional but it is here to facilitate your experience with Curve-X.

**Folder structure:**
+ **`include/curve-x/`** contains header files that you, as the library user, want to use inside your project. The most important one is `curve.h`, containing all required definitions to start using the library. If you want to have a deep-dive into the code, I'd recommend you to check the header files in this order: `point.h`, `utils.h`, `key.h`, `curve.h` and finally `curve-serializer.h`.
+ **`src/`** contains source files and implementations of the header files located in the folder `include/curve-x/`.
+ **`tests/`** contains source files for testing and usage examples. You may want to look at it to better understand how to use the library.
+ **`samples/`** contains samples of curve files generated by the library. You can import these inside the [GUI editor](https://github.com/arkaht/cpp-curve-editor-x) or in your code for testing. It's also here so you can get a grasp of what the text format is.

## Code Example
From [`tests/simple_example.cpp`](https://github.com/arkaht/cpp-curve-x/tree/master/tests/simple_example.cpp):
```cpp
// Includes all necessary code including the Curve class
#include
// Includes the CurveSerializer class, only if you want to import or export
// the curves data from or to files
#include

// Includes std::ofstream to output the curve data to files
#include

int main()
{
// Initialize a curve object
curve_x::Curve curve;

// Add two keys with different control points
curve.add_key( curve_x::CurveKey( { 0.0f, 0.0f } ) );
curve.add_key( curve_x::CurveKey( { 1.0f, 1.0f } ) );

// Evaluate the curve at x=0.3f
float time = 0.3f;
float value = curve.evaluate_by_time( time );
printf( "Evaluation for x=%f: y=%f\n\n", time, value );
// Output:
// Evaluation for x=0.300000: y=0.216000

// Serialize the curve into a string
curve_x::CurveSerializer serializer;
std::string data = serializer.serialize( curve );
printf( "Curve serialized data:\n%s\n", data.c_str() );
// Output:
// Curve serialized data:
// version:1
// 0:x=0.000000;y=0.000000,x=-1.000000;y=0.000000,x=1.000000;y=0.000000,0
// 1:x=1.000000;y=1.000000,x=-1.000000;y=0.000000,x=1.000000;y=0.000000,0

// Write the serialized curve into a file
std::ofstream file( "my_curve.cvx" );
file << data;
file.close();
}
```

For more examples, look at the [`tests/`](https://github.com/arkaht/cpp-curve-x/tree/master/tests) folder.

## Getting Started
This project is built using **CMake 3.11**. However, with proper setup it is not required to add it inside your projects.

### Add Curve-X to your project
With CMake

```
/
├── libs/
│ ├── curve-x/
│ │ ├── include/
│ │ │ └── ...
│ │ ├── src/
│ │ │ └── ...
│ │ ├── CMakeLists.txt
│ │ └── ...
│ └── ...
├── main.cpp
├── CMakeLists.txt
└── ...
```
3. Optionally, delete folders that aren't required for your project such as `samples/` and `tests/`.
4. In `/CMakeLists.txt`:
+ Use `add_subdirectory` with the library's path to include it:
```cmake
add_subdirectory("libs/curve-x")
```
+ Link the library to your project with `target_link_libraries`:
```cmake
target_link_libraries( PRIVATE curve-x )
```
5. In your code, use the library, for example in your `main.cpp`:
```cpp
#include

// ...

int main()
{
curve_x::Curve curve;

// ...
}
```
6. Compile and run your project, you're ready to go!

Without CMake

1. Clone `arkaht/cpp-curve-x` or [download the ZIP](https://github.com/arkaht/cpp-curve-x/archive/refs/heads/master.zip) and extract it
2. Move the `curve-x` folder inside your project libraries folder, for example:
```
/
├── libs/
│ ├── curve-x/
│ │ ├── include/
│ │ │ └── ...
│ │ ├── src/
│ │ │ └── ...
│ │ └── ...
│ └── ...
├── main.cpp
└── ...
```
3. Optionally, delete folders that aren't required for your project such as `samples/` and `tests/`.
4. Add an additional include directory at `libs/curve-x/include/`.
5. Add the source files at `libs/curve-x/src/*.cpp` to be compiled.
5. In your code, use the library, for example in your `main.cpp`:
```cpp
#include

// ...

int main()
{
curve_x::Curve curve;

// ...
}
```
6. Compile and run your project, you're ready to go!

### Build the project
> [!NOTE]
> *As I don't have **Linux** or **MacOS** machines, the following instructions have been written only for **Windows**.* If you know how to do it in those platforms, I'd welcome a pull request!

Visual Studio Code

1. Install **Visual Studio Code** extensions [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) and [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) from Microsoft.
2. Clone `arkaht/cpp-curve-x` or [download the ZIP](https://github.com/arkaht/cpp-curve-x/archive/refs/heads/master.zip) and extract it
3. Open the project's folder inside **Visual Studio Code**
4. Configure the project with **CMake** (`Ctrl+Shift+P > CMake: Configure`)
5. Build the project with **CMake** (`Ctrl+Shift+P > CMake: Build`, `F7` or `⚙ Build` button at the bottom-left)
6. Run the project examples, you're ready to make changes!

Visual Studio 2022

1. Clone `arkaht/cpp-curve-x` or [download the ZIP](https://github.com/arkaht/cpp-curve-x/archive/refs/heads/master.zip) and extract it
2. Open the project's folder inside **Visual Studio 2022**
3. Once the project has been automatically configured, run the project examples, you're ready to make changes!

## Why did I make it?
Originally, it was because I wanted time-based curves for my game engine so I could better control the feeling of my games, especially when I wanted to tweak each parameter of my explosion effects (i.e. transform scales and color lerps) with precise control and better visualization instead of having to hardcode them one by one. I wanted something very similar to implementations in popular engines like Unreal, Unity or Godot.

I searched but couldn't find a C++ curve library that would suits my needs: a library easy-to-use, small to install and a GUI editor compatible with it.

Then, as I'm still a student, it also became a learning project to know more about curves.

It is also my first time using CMake and Git Submodules (used in the [editor repository](https://github.com/arkaht/cpp-curve-editor-x)).

## Credits
This library has been possible thanks to all these online resources:
+ [The Continuity of Splines](https://www.youtube.com/watch?v=jvPPXbo87ds) by **Freya Holmér**
+ [Cubic Hermite spline](https://en.wikipedia.org/wiki/Cubic_Hermite_spline) from **Wikipedia**
+ [Bézier spline](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) from **Wikipedia**
+ [Curves and Splines](https://catlikecoding.com/unity/tutorials/curves-and-splines/) from **Catlike Coding**
+ [A Primer on Bézier Curve](https://pomax.github.io/BezierInfo-2/) by **Pomax**
+ **Unreal Engine**'s `FRichCurve` code for evaluation by time