      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
    200

    //! # [![](http://meritbadge.herokuapp.com/ocl)](https://crates.io/crates/ocl) | [GitHub](https://github.com/cogciprocate/ocl)
    //!
    //! Rust implementation of the [OpenCL&trade; 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.17")]

    // #![warn(missing_docs)]

    extern crate num_traits;
    extern crate futures;
    #[macro_use]
    extern crate failure;
    pub extern crate ocl_core as core;

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

    pub use self::standard::{Platform, Extensions, Device, Context, Program, Queue, Kernel, Buffer, Image, Event,
        EventList, EventArray, Sampler, SpatialDims, ProQue, BufferCmdError};
    pub use self::async::{MemMap, FutureMemMap, RwVec, ReadGuard, WriteGuard,
        FutureReadGuard, FutureWriteGuard};
    pub use 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,
            KernelBuilder};
        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::{ArgVal, ContextPropertyValue, PlatformInfoResult, DeviceInfoResult,
            ContextInfoResult, CommandQueueInfoResult, MemInfoResult, ImageInfoResult,
            SamplerInfoResult, ProgramInfoResult, ProgramBuildInfoResult, KernelInfoResult,
            KernelArgInfoResult, KernelWorkGroupInfoResult, EventInfoResult, ProfilingInfoResult};

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)