1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199

//! # [![](http://meritbadge.herokuapp.com/ocl)](https://crates.io/crates/ocl) | [GitHub](https://github.com/cogciprocate/ocl)
//!
//! Rust implementation of the [OpenCL™ API].
//!
//! Some versions of this documentation are built from development branches
//! and may differ slightly between what is on crates.io and the master
//! branch. See the [repo page](https://github.com/cogciprocate/ocl) for links
//! to both versions.
//!
//! Please report unclear documentation or places where examples would be
//! appreciated by filing an [issue].
//!
//!
//! ## Foundations
//!
//! For lower level interfaces and to use `OpenCL` features that have not yet
//! been implemented on the `standard` (high-level) interface types, see the
//! [`ocl-core`] and [`cl-sys`] crates.
//!
//!
//! ## Help Wanted
//!
//! Please request or help complete any functionality you may need by filing
//! an [issue] or creating a [pull
//! request](https://github.com/cogciprocate/ocl/pulls).
//!
//! Keep an eye out for places where examples would be useful and let us know!
//!
//!
//! ## Feedback appreciated
//!
//! Suggestions and nitpicks are most welcome. Don't hesitate to file an
//! [issue] just to offer constructive criticism.
//!
//!
//! <br/>
//! *“`OpenCL` and the `OpenCL` logo are trademarks of Apple Inc. used by permission by Khronos.”*
//!
//!
//! [OpenCL&trade; API]: https://www.khronos.org/registry/OpenCL/
//! [issue]: https://github.com/cogciprocate/ocl/issues
//! [`ocl-core`]: https://github.com/cogciprocate/ocl-core
//! [`cl-sys`]: https://github.com/cogciprocate/cl-sys
//! [`Result`]: /ocl/ocl/type.Result.html
//! [examples]: https://github.com/cogciprocate/ocl/tree/master/examples

#![doc(html_root_url = "https://docs.rs/ocl/0.13")]

// #![warn(missing_docs)]

extern crate libc;
extern crate num;
#[cfg(test)]
extern crate rand;
extern crate futures;
extern crate crossbeam;
pub extern crate ocl_core as core;

#[cfg(test)]
mod tests;
mod standard;
pub mod async;

pub use self::standard::{Platform, Device, Context, Program, Queue, Kernel, Buffer, Image, Event,
    EventList, EventArray, Sampler, SpatialDims, ProQue};
pub use self::async::{MemMap, FutureMemMap, RwVec, ReadGuard, WriteGuard, FutureRwGuard,
    FutureReader, FutureWriter};
pub use core::error::{Error, Result};
#[doc(no_inline)]
pub use core::ffi;
#[doc(no_inline)]
pub use core::util;
#[doc(no_inline)]
pub use core::{OclPrm, OclScl, OclVec, DeviceType, CommandQueueProperties, MemFlags, MapFlags};


pub mod prm {
    //! OpenCL scalar and vector primitive types.
    //!
    //! Rust primitives may have subtly different behaviour than OpenCL
    //! primitives within kernels. Wrapping is one example of this. Scalar
    //! integers within Rust may do overflow checks where in the kernel they
    //! do not. Therefore OpenCL-compatible implementations of each of the
    //! types are provided so that host and device side operations can be
    //! perfectly consistent.
    //!
    //! The `cl_...` (`cl_uchar`, `cl_int`, `cl_float`, etc.) types are simple
    //! aliases of the Rust built-in primitive types and do **not** behave the
    //! same way that the kernel-side equivalents do. The uppercase-named
    //! types, on the other hand, (`Uchar`, `Int`, `Float`, etc.) are designed
    //! to behave identically to their corresponding types within kernels.
    //!
    //! Please file an issue if any of the uppercase-named kernel-mimicking
    //! types deviate from what they should (as they are reasonably new this
    //! is definitely something to watch out for).
    //!
    //! Vector type fields can be accessed using index operations i.e. [0],
    //! [1], [2] ... etc. Plans for other ways of accessing fields (such as
    //! `.x()`, `.y()`, `.s0()`, `.s15()`, etc.) will be considered in the
    //! future (pending a number of additions/stabilizations to the Rust
    //! language). Create an issue if you have an opinion on the matter.
    //!
    //! [NOTE]: This module may be renamed.

    pub use ffi::{cl_char, cl_uchar, cl_short, cl_ushort, cl_int, cl_uint, cl_long, cl_ulong,
        cl_half, cl_float, cl_double, cl_bool, cl_bitfield};

    pub use ffi::{ cl_GLuint, cl_GLint, cl_GLenum };

    // Wrapping types. Use these to mimic in-kernel behaviour:
    pub use core::{
        Char, Char2, Char3, Char4, Char8, Char16,
        Uchar, Uchar2, Uchar3, Uchar4, Uchar8, Uchar16,
        Short, Short2, Short3, Short4, Short8, Short16,
        Ushort, Ushort2, Ushort3, Ushort4, Ushort8, Ushort16,
        Int, Int2, Int3, Int4, Int8, Int16,
        Uint, Uint2, Uint3, Uint4, Uint8, Uint16,
        Long, Long2, Long3, Long4, Long8, Long16,
        Ulong, Ulong2, Ulong3, Ulong4, Ulong8, Ulong16,
        Float, Float2, Float3, Float4, Float8, Float16,
        Double, Double2, Double3, Double4, Double8, Double16};
}

pub mod traits {
    //! Commonly used traits.

    pub use standard::{WorkDims, MemLen, IntoMarker, IntoRawEventArray};
    pub use core::{OclPrm, OclScl, OclVec};
}

pub mod builders {
    //! Builders and associated settings-related types.

    pub use standard::{ContextBuilder, BuildOpt, ProgramBuilder, ImageBuilder, ProQueBuilder,
        DeviceSpecifier, BufferCmdKind, BufferCmdDataShape, BufferCmd, BufferReadCmd,
        BufferWriteCmd, BufferMapCmd, ImageCmdKind, ImageCmd, KernelCmd, BufferBuilder};
    pub use standard::{ClNullEventPtrEnum, ClWaitListPtrEnum};
    pub use core::{ImageFormat, ImageDescriptor, ContextProperties};
    // #[cfg(not(release))] pub use standard::BufferTest;
}

pub mod flags {
    //! Bitflags for various parameter types.

    pub use core::{
        // cl_device_type - bitfield
        DeviceType, DEVICE_TYPE_DEFAULT, DEVICE_TYPE_CPU, DEVICE_TYPE_GPU, DEVICE_TYPE_ACCELERATOR,
            DEVICE_TYPE_CUSTOM, DEVICE_TYPE_ALL,
        // cl_device_fp_config - bitfield
        DeviceFpConfig, FP_DENORM, FP_INF_NAN, FP_ROUND_TO_NEAREST, FP_ROUND_TO_ZERO,
            FP_ROUND_TO_INF, FP_FMA, FP_SOFT_FLOAT, FP_CORRECTLY_ROUNDED_DIVIDE_SQRT,
        // cl_device_exec_capabilities - bitfield
        DeviceExecCapabilities, EXEC_KERNEL, EXEC_NATIVE_KERNEL,
        // cl_command_queue_properties - bitfield
        CommandQueueProperties, QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE, QUEUE_PROFILING_ENABLE,
        // cl_device_affinity_domain
        DeviceAffinityDomain, DEVICE_AFFINITY_DOMAIN_NUMA, DEVICE_AFFINITY_DOMAIN_L4_CACHE,
            DEVICE_AFFINITY_DOMAIN_L3_CACHE, DEVICE_AFFINITY_DOMAIN_L2_CACHE,
            DEVICE_AFFINITY_DOMAIN_L1_CACHE, DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE,
        // cl_mem_flags - bitfield
        MemFlags, MEM_READ_WRITE, MEM_WRITE_ONLY, MEM_READ_ONLY, MEM_USE_HOST_PTR,
            MEM_ALLOC_HOST_PTR, MEM_COPY_HOST_PTR, MEM_HOST_WRITE_ONLY, MEM_HOST_READ_ONLY,
            MEM_HOST_NO_ACCESS,
        // cl_mem_migration_flags - bitfield
        MemMigrationFlags, MIGRATE_MEM_OBJECT_HOST, MIGRATE_MEM_OBJECT_CONTENT_UNDEFINED,
        // cl_map_flags - bitfield
        MapFlags, MAP_READ, MAP_WRITE, MAP_WRITE_INVALIDATE_REGION,
        // cl_program_binary_type
        ProgramBinaryType, PROGRAM_BINARY_TYPE_NONE, PROGRAM_BINARY_TYPE_COMPILED_OBJECT,
            PROGRAM_BINARY_TYPE_LIBRARY, PROGRAM_BINARY_TYPE_EXECUTABLE,
        // cl_kernel_arg_type_qualifer
        KernelArgTypeQualifier, KERNEL_ARG_TYPE_NONE, KERNEL_ARG_TYPE_CONST,
            KERNEL_ARG_TYPE_RESTRICT, KERNEL_ARG_TYPE_VOLATILE,
    };
}

pub mod enums {
    //! Enumerators for settings and information requests.

    pub use standard::{DeviceSpecifier, BufferCmdKind, BufferCmdDataShape};

    // API enums.
    pub use core::{ImageChannelOrder, ImageChannelDataType, Cbool, Polling, PlatformInfo,
        DeviceInfo, DeviceMemCacheType, DeviceLocalMemType, ContextInfo, ContextProperty,
        ContextInfoOrPropertiesPointerType, DevicePartitionProperty, CommandQueueInfo, ChannelType,
        MemObjectType, MemInfo, ImageInfo, AddressingMode, FilterMode, SamplerInfo, ProgramInfo,
        ProgramBuildInfo, ProgramBuildStatus, KernelInfo, KernelArgInfo, KernelArgAddressQualifier,
        KernelArgAccessQualifier, KernelWorkGroupInfo, EventInfo, CommandType,
        CommandExecutionStatus, BufferCreateType, ProfilingInfo};

    // Custom enums.
    pub use core::{KernelArg, ContextPropertyValue, PlatformInfoResult, DeviceInfoResult,
        ContextInfoResult, CommandQueueInfoResult, MemInfoResult, ImageInfoResult,
        SamplerInfoResult, ProgramInfoResult, ProgramBuildInfoResult, KernelInfoResult,
        KernelArgInfoResult, KernelWorkGroupInfoResult, EventInfoResult, ProfilingInfoResult};

    // Error status.
    pub use core::Status;
}