You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

117 lines
4.6 KiB

4 years ago
* GHOST Rust bindings
Rust bindings and interop for GHOST.
** Layout
ABI-compatable types and functions are all prefixed with `GHOST_` and are exported in the `c` module (TODO).
I've attempted to provide more Rust-idiomatic API variants as well, which have non-prefixed names.
** Notes
Eventually I intend to have /most/ (if not all) C compatable types either reimplemented or aliased to non-prefixed Rust types.
At present though this is not the case, and prefixed names that can double as ergonomic Rust types are not aliased to them, so you'll have to use both often.
The reimplementation is undergoing, the aliasing not yet.
I've elected to leave out implementing ~Copy~ for /most/ FFI types, because I think the ownership model will work well here.
This may be changed in the future, as (virtually) all implement ~Clone~ anyway.
I did this basically just because I want people to think about it when and why they copy something, instead of it being default behaviour.
** Implementation
4 years ago
*** Implemented C compatable ABI
Note: List is in-progress and doesn't show everything
- [-] `GHOST_Types.h`
- [X] /Handles/
4 years ago
- [X] GHOST_SystemHandle
- [X] GHOST_TimerTaskHandle
- [X] GHOST_WindowHandle
- [X] GHOST_EventHandle
- [X] GHOST_RectangleHandle
- [X] GHOST_EventConsumerHandle
- [X] GHOST_ContextHandle
- [X] GHOST_XrContextHandle
4 years ago
- [-] /Primitives/ (ones that begin with =T= I count as `primitive')
4 years ago
- [X] GHOST_TInt8
- [X] GHOST_TUns8
- [X] GHOST_Tint16
- [X] GHOST_TUns16
- [X] GHOST_Tint32
- [X] GHOST_TUns32
- [X] GHOST_TInt64
- [X] GHOST_TUns64
- [X] GHOST_TUserDataPtr
- [X] GHOST_TSuccess
- [X] GHOST_TTabletMode
- [X] GHOST_TTabletAPI
- [X] GHOST_TVisibility
- [X] GHOST_TFireTimeConstant
- [X] GHOST_TModifierKeyMask
- [X] GHOST_TWindowState
- [X] GHOST_TWindowOrder
- [X] GHOST_TDrawingContextType
- [X] GHOST_TButtonMask
- [X] GHOST_TEventType
- [ ] GHOST_TStandardCursor
- [ ] GHOST_TKey
4 years ago
- [X] /Structures/
4 years ago
- [X] GHOST_GLSettings
- [X] GHOST_GLFlags
- [X] GHOST_DialogOptions
- [X] GHOST_TabletData
4 years ago
- [X] /Constants/
- [X] =GHOST_TABLET_DATA_NONE= (reimpl as ~const fn GHOST_TabletData::none()~)
4 years ago
*** Native Rust API
I provide more Rust idiomatic API for some things.
They may or may not share ABI, if they do they will have type aliases to the corresponding ~GHOST_~ identifier, so always use those when ABI compatability is desired.
4 years ago
**** Overview
List and implementation status of features
4 years ago
- [-] Types
- [X] [[Handles]]: ~handle.rs~
- [X] [[Error handling]]: ~error.rs~
4 years ago
- [ ] Events: ~event.rs~
4 years ago
**** Handles
Handles keep the C ABI, but are re-wrtten with traits to be more idiomatic.
The trait ~GhostHandle~ is provided, which should be implemented on a structure that is not intended to be instantiated, but instead used as a `marker' for `Handle<T>'.
These types are ABI equivalent, and are present (with their corresponding ~GHOST_~ alias in =handle.rs=)
Since handles are just types pointers, they are only ever used as such and shouldn't exist themselves.
***** Example
#+BEGIN_SRC rust
extern "C" {fn some_internal_call(window: GHOST_WindowHandle) -> GHOST_TSuccess;}
4 years ago
fn do_something_to_window(window: &mut Handle<Window>) -> GhostResult<()>
4 years ago
{
some_internal_call(window as GHOST_WindowHandle).into()
4 years ago
}
4 years ago
#+END_SRC
**** Error handling
I have provided an idiomatic Rust error handling module, with conversion and interop between the C ABI ~GHOST_TSuccess~ and the Rust ~error::GhostError~.
There is also the type alias ~GhostResult~ provided.
On =nightly= Rust versions, values of type ~GHOST_TSuccess~ can be propagated directly with ~?~, but on stable they must be propagated through ~GhostResult~:
#+BEGIN_SRC rust
extern "C" {fn returns_tsuccess() -> GHOST_TSuccess;}
fn try_things_internal() -> GhostResult // On nightly, we can propagage `GHOST_TSuccess` directly here, but it's still more desireable for us to have a `Result<T,E>` instead of an integer in Rust, so this is still preferrable.
{
returns_tsuccess()?;
Ok(())
}
fn caller()
{
match try_things_internal() {
Ok(_) => println!("Yay!"),
Err(_) => panic!("Fug"),
}
}
#+END_SRC
Keeping such a style is /usually/ preferred, anyhow.
See [[./src/error.rs][error.rs]] for more details.