mirror of
https://github.com/cccb/servicepoint.git
synced 2025-01-18 10:00:14 +01:00
expanded README
This commit is contained in:
Vinzenz Schroeter
parent
ea7061db7f
commit
6355b430ee
131
README.md
131
README.md
|
|
@ -1,4 +1,4 @@
|
|||
# servicepoint
|
||||
# servicepoint2
|
||||
|
||||
[](https://crates.io/crates/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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue