servicepoint/servicepoint-binding-csharp
0
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

expanded README

Browse source
This commit is contained in:
Vinzenz Schroeter 2024-05-13 18:59:31 +02:00
parent ea7061db7f
commit 6355b430ee
1 changed files with 120 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

131
README.md
View file

@ -1,4 +1,4 @@
# servicepoint
# servicepoint2
[![crates.io](https://img.shields.io/crates/v/servicepoint2.svg)](https://crates.io/crates/servicepoint2)
[![Crates.io Total Downloads](https://img.shields.io/crates/d/servicepoint2)](https://crates.io/crates/servicepoint2)
@ -9,21 +9,51 @@ In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wa
Display" or "Airport Display".
This repository contains a library for parsing, encoding and sending packets to this display via UDP.
## Note on stability
This library is still in early development.
You can absolutely use it and it works, but expect minor breaking changes with every version bump.
Please specify the full version including patch in your Cargo.toml until 1.0 is released.
### Installation
Expect bugs and/or missing features in the language bindings for now. If you need something specific, open an issue or a pull request.
## Installation
### Rust
```bash
# release version
cargo add servicepoint2
# development version
cargo add --git https://github.com/kaesaecracker/servicepoint.git
```
### Example
### C# / F#
(!) not published yet - build from source
```
dotnet add ServicePoint2
```
You will also need a `cdylib` build of the native library at runtime for the relevant platform. On Linux/macOS/BSD, this should be `target/release/libservicepoint2.so`.
As there is no API stability yet, your language binding has to match the used library version exactly.
### C
Copy the header to your project and compile against.
You have the choice of linking statically (recommended) or dynamically.
- The C example shows how to link statically against the `staticlib` variant.
- When linked dynamically, you have to provide the `cdylib` at runtime in the _same_ version, as there are no API/ABI guarantees yet.
## Examples
More are available in the `examples` folder.
### Rust
This is where the library works the best.
Any API usage accepted by the compiler in a safe context is either safe or buggy (issues welcome).
```rust
fn main() {
@ -37,9 +67,72 @@ fn main() {
}
```
More are available in the `examples` folder.
### C# / F#
### Features
Uses C bindings internally to provide a similar API to rust. Things to keep in mind:
- You will get a `NullPointerException` when trying to call a method where the native instance has been consumed already (e.g. when `Send`ing a command instance twice). Send a clone instead of the original if you want to keep using it.
- Some lower-level APIs _will_ panic in native code when used improperly.
Example: manipulating the `Span<byte>` of an object after freeing the instance.
- C# specifics are documented in the library. Use the rust documentation for everything else. Naming and semantics are the same apart from CamelCase instead of kebap_case.
- You will only get rust backtraces in debug builds of the native code.
- F# is not explicitly tested. If there are usability or functionality problems, please open an issue.
```csharp
using ServicePoint2;
// using statement calls Dispose() on scope exit, which frees unmanaged instances
using var connection = Connection.Open("127.0.0.1:2342");
using var pixels = PixelGrid.New(Constants.PixelWidth, Constants.PixelHeight);
while (true)
{
pixels.Fill(true);
connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone()));
Thread.Sleep(5000);
pixels.Fill(false);
connection.Send(Command.BitmapLinearWin(0, 0, pixels.Clone()));
Thread.Sleep(5000);
}
```
### C and other languages
The lowest common denominator. Things to keep in mind:
- This is a chainsaw. You will cut your leg.
- function names are: `sp2_` \<struct_name\> \<rust name\>.
- Use the rust documentation.
- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free.
- Option<T> or Result<T, E> turn into nullable return values - check for NULL!
- There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable.
```c++
#include <stdio.h>
#include "servicepoint2.h"
int main(void) {
sp2_Connection *connection = sp2_connection_open("localhost:2342");
if (connection == NULL)
return 1;
sp2_PixelGrid *pixels = sp2_pixel_grid_new(sp2_PIXEL_WIDTH, sp2_PIXEL_HEIGHT);
sp2_pixel_grid_fill(pixels, true);
command = sp2_command_bitmap_linear_win(0, 0, pixels); // pixels get consumed here
if (command == NULL)
return 4;
if (!sp2_connection_send(connection, command)) // command gets consumed here
return 5;
// connection does not get consumed and has to be freed manually
sp2_connection_dealloc(connection);
return 0;
}
```
## Features
This library has multiple compression libraries as optional dependencies.
If you do not need compression/decompression support you can disable those features.
@ -52,6 +145,22 @@ default-features = false
features = ["compression-bz"]
```
### Projects using the library
Language bindings will not know which features are available and may fail at runtime.
It is recommended to include all features for builds used outside of rust.
- screen emulator: https://github.com/kaesaecracker/pixel-receiver-rs
## Projects using the library
- screen simulator (rust): https://github.com/kaesaecracker/pixel-receiver-rs
- tanks game (C#): https://github.com/kaesaecracker/cccb-tanks-cs
To add yourself to the list, open a pull request.
## Where is servicepoint1?
This library is a spiritual mix of a not-yet-working rust library called `servicepoint` and a bunch of working but also unfinished C# code. Because most of the API concept and a bunch of code is taken from the rust library, the result is called `servicepoint2`.
## Contributing
Contributions are accepted in any form (issues, documentation, feature requests, code, review, ...).
All creatures welcome.