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
117 lines
4.6 KiB
* 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
|
|
|
|
*** Implemented C compatable ABI
|
|
Note: List is in-progress and doesn't show everything
|
|
|
|
- [-] `GHOST_Types.h`
|
|
- [X] /Handles/
|
|
- [X] GHOST_SystemHandle
|
|
- [X] GHOST_TimerTaskHandle
|
|
- [X] GHOST_WindowHandle
|
|
- [X] GHOST_EventHandle
|
|
- [X] GHOST_RectangleHandle
|
|
- [X] GHOST_EventConsumerHandle
|
|
- [X] GHOST_ContextHandle
|
|
- [X] GHOST_XrContextHandle
|
|
- [-] /Primitives/ (ones that begin with =T= I count as `primitive')
|
|
- [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
|
|
- [X] /Structures/
|
|
- [X] GHOST_GLSettings
|
|
- [X] GHOST_GLFlags
|
|
- [X] GHOST_DialogOptions
|
|
- [X] GHOST_TabletData
|
|
- [X] /Constants/
|
|
- [X] =GHOST_TABLET_DATA_NONE= (reimpl as ~const fn GHOST_TabletData::none()~)
|
|
|
|
*** 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.
|
|
|
|
**** Overview
|
|
List and implementation status of features
|
|
|
|
- [-] Types
|
|
- [X] [[Handles]]: ~handle.rs~
|
|
- [X] [[Error handling]]: ~error.rs~
|
|
- [ ] Events: ~event.rs~
|
|
|
|
**** 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;}
|
|
|
|
fn do_something_to_window(window: &mut Handle<Window>) -> GhostResult<()>
|
|
{
|
|
some_internal_call(window as GHOST_WindowHandle).into()
|
|
}
|
|
#+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.
|