split README
This commit is contained in:
Vinzenz Schroeter
parent
3780c2063d
commit
ccbba9ad83
8 changed files with 199 additions and 146 deletions
|
|
@ -7,7 +7,7 @@ license = "GPL-3.0-or-later"
|
|||
description = "A rust library for the CCCB Service Point Display."
|
||||
homepage = "https://docs.rs/crate/servicepoint"
|
||||
repository = "https://github.com/cccb/servicepoint"
|
||||
readme = "../../README.md"
|
||||
readme = "README.md"
|
||||
|
||||
[lib]
|
||||
crate-type = ["rlib"]
|
||||
|
|
|
|||
54
crates/servicepoint/README.md
Normal file
54
crates/servicepoint/README.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# servicepoint
|
||||
|
||||
[](https://crates.io/crates/servicepoint)
|
||||
[](https://crates.io/crates/servicepoint)
|
||||
[](https://docs.rs/servicepoint/latest/servicepoint/)
|
||||
[](../../LICENSE)
|
||||
|
||||
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
|
||||
Display" or "Airport Display".
|
||||
This crate contains a library for parsing, encoding and sending packets to this display via UDP.
|
||||
|
||||
## Examples
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
// establish connection
|
||||
let connection = servicepoint::Connection::open("172.23.42.29:2342")
|
||||
.expect("connection failed");
|
||||
|
||||
// clear screen content
|
||||
connection.send(servicepoint::Command::Clear.into())
|
||||
.expect("send failed");
|
||||
}
|
||||
```
|
||||
|
||||
More examples are available in the crate.
|
||||
Execute `cargo run --example` for a list of available examples and `cargo run --example <name>` to run one.
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
cargo add servicepoint
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
This library has multiple compression libraries as optional dependencies.
|
||||
If you do not need compression/decompression support you can disable those features.
|
||||
In the likely case you only need one of them, you can include that one specifically.
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
servicepoint = { version = "0.5.0", default-features = false, features = ["compression-bz"] }
|
||||
```
|
||||
|
||||
## Everything else
|
||||
|
||||
Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information.
|
||||
|
|
@ -7,7 +7,7 @@ license = "GPL-3.0-or-later"
|
|||
description = "C bindings for the servicepoint crate."
|
||||
homepage = "https://docs.rs/crate/servicepoint"
|
||||
repository = "https://github.com/cccb/servicepoint"
|
||||
readme = "../../README.md"
|
||||
readme = "README.md"
|
||||
links = "servicepoint"
|
||||
|
||||
[lib]
|
||||
|
|
|
|||
63
crates/servicepoint_binding_c/README.md
Normal file
63
crates/servicepoint_binding_c/README.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
# servicepoint_binding_c
|
||||
|
||||
[](https://crates.io/crates/servicepoint)
|
||||
[](https://crates.io/crates/servicepoint)
|
||||
[](https://docs.rs/servicepoint/latest/servicepoint/)
|
||||
[](../../LICENSE)
|
||||
|
||||
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
|
||||
Display" or "Airport Display".
|
||||
This crate contains C bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP.
|
||||
|
||||
## Examples
|
||||
|
||||
```c++
|
||||
#include <stdio.h>
|
||||
#include "servicepoint.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);
|
||||
|
||||
sp2_Command *command = sp2_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
|
||||
sp2_Packet *packet = sp2_packet_from_command(command);
|
||||
if (!sp2_connection_send(connection, packet))
|
||||
return 1;
|
||||
|
||||
sp2_connection_dealloc(connection);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
A full example including Makefile is available as part of this crate.
|
||||
|
||||
## 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
|
||||
|
||||
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.
|
||||
|
||||
## Notes on differences to rust library
|
||||
|
||||
- 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.
|
||||
- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
|
||||
|
||||
## Everything else
|
||||
|
||||
Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information.
|
||||
|
|
@ -3,7 +3,7 @@ name = "servicepoint_binding_cs"
|
|||
version.workspace = true
|
||||
edition = "2021"
|
||||
publish = false
|
||||
readme = "../../README.md"
|
||||
readme = "README.md"
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib"]
|
||||
|
|
|
|||
65
crates/servicepoint_binding_cs/README.md
Normal file
65
crates/servicepoint_binding_cs/README.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
# ServicePoint
|
||||
|
||||
In [CCCB](https://berlin.ccc.de/), there is a big pixel matrix hanging on the wall. It is called "Service Point
|
||||
Display" or "Airport Display".
|
||||
This crate contains C# bindings for the `servicepoint` library, enabling users to parse, encode and send packets to this display via UDP.
|
||||
|
||||
## Examples
|
||||
|
||||
```csharp
|
||||
using ServicePoint;
|
||||
|
||||
// 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);
|
||||
}
|
||||
```
|
||||
|
||||
A full example including project files is available as part of this crate.
|
||||
|
||||
## 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.
|
||||
|
||||
## Installation
|
||||
|
||||
NuGet packages are not a good way to distribute native projects ([relevant issue](https://github.com/dotnet/sdk/issues/33845)).
|
||||
Because of that, there is no NuGet package you can use directly.
|
||||
Including this repository as a submodule and building from source is the recommended way of using the library.
|
||||
|
||||
```bash
|
||||
git submodule add https://github.com/kaesaecracker/servicepoint.git
|
||||
git commit -m "add servicepoint submodule"
|
||||
```
|
||||
|
||||
You can now reference `servicepoint-bindings-cs/src/ServicePoint.csproj` in your project.
|
||||
The rust library will automatically be built.
|
||||
|
||||
Please provide more information in the form of an issue if you need the build to copy a different library file for your platform.
|
||||
|
||||
## Notes on differences to rust library
|
||||
|
||||
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 kebab_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.
|
||||
- Reading and writing to instances concurrently is not safe. Only reading concurrently is safe.
|
||||
|
||||
## Everything else
|
||||
|
||||
Look at the main project [README](https://github.com/cccb/servicepoint/blob/main/README.md) for further information.
|
||||
|
|
@ -56,7 +56,7 @@
|
|||
|
||||
<ItemGroup>
|
||||
<!-- include link to source code at revision -->
|
||||
<None Include="../../../README.md" Pack="true" PackagePath="\"/>
|
||||
<None Include="../README.md" Pack="true" PackagePath="\"/>
|
||||
<!-- add README.md to package -->
|
||||
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
|
||||
</ItemGroup>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue