Struct three::Factory

pub struct Factory { /* private fields */ }

Factory is used to instantiate game objects.

Implementations

impl Factory

pub fn scene(&mut self) -> Scene

Create new empty Scene.

pub fn instantiate_template(&mut self, template: &Template) -> (Group, Vec<Clip>)

Creates an instance of all the objects described in the template.

Returns a Group that is the root object for all objects created from the template, as well as a list of all animation clips instantiated from the template.

See the module documentation for template for more information on the template system.

Examples

Create an empty template and then instantiate it, effectively the most verbose way to call Factory::group:

use three::template::Template;

let template = Template::new();
let (group, animations) = window.factory.instantiate_template(&template);

pub fn bone(
    &mut self,
    index: usize,
    inverse_bind_matrix: InverseBindMatrix
) -> Bone

Create a new Bone, one component of a Skeleton.

pub fn skeleton(&mut self, bones: Vec<Bone>) -> Skeleton

Create a new Skeleton from a set of Bone instances.

• bones is the array of bones that form the skeleton.
• inverses is an optional array of inverse bind matrices for each bone. Skeleton: ../skeleton/struct.Skeleton.html Bone: ../skeleton/struct.Bone.html

pub fn camera<P: Into<Projection>>(&mut self, projection: P) -> Camera

Create a new camera using the provided projection.

This allows you to create a camera from a predefined projection, which is useful if you e.g. load projection data from a file and don’t necessarily know ahead of time what type of projection the camera uses. If you’re manually creating a camera, you should use [perspective_camera] or [orthographic_camera].

pub fn orthographic_camera<P: Into<Point2<f32>>>(
    &mut self,
    center: P,
    extent_y: f32,
    range: Range<f32>
) -> Camera

Create new Orthographic Camera. It’s used to render 2D.

pub fn perspective_camera<R: Into<ZRange>>(
    &mut self,
    fov_y: f32,
    range: R
) -> Camera

Create new Perspective Camera.

It’s used to render 3D.

Examples

Creating a finite perspective camera.

let camera = factory.perspective_camera(60.0, 0.1 .. 1.0);

Creating an infinite perspective camera.

let camera = factory.perspective_camera(60.0, 0.1 ..);

pub fn group(&mut self) -> Group

Create empty Group.

pub fn upload_geometry(&mut self, geometry: Geometry) -> InstancedGeometry

Uploads geometry data to the GPU so that it can be reused for instanced rendering.

See the module documentation in template for information on mesh instancing and its benefits.

Examples

use three::Geometry;

// Create geometry for a triangle.
let vertices = vec![
    [-0.5, -0.5, -0.5].into(),
    [0.5, -0.5, -0.5].into(),
    [0.0, 0.5, -0.5].into(),
];
let geometry = Geometry::with_vertices(vertices);

// Upload the triangle data to the GPU.
let upload_geometry = window.factory.upload_geometry(geometry);

// Create multiple meshes with the same GPU data and material.
let material = three::material::Basic {
    color: 0xFFFF00,
    map: None,
};
let first = window.factory.create_instanced_mesh(&upload_geometry, material.clone());
let second = window.factory.create_instanced_mesh(&upload_geometry, material.clone());
let third = window.factory.create_instanced_mesh(&upload_geometry, material.clone());

pub fn mesh<M: Into<Material>>(&mut self, geometry: Geometry, material: M) -> Mesh

Create new Mesh with desired Geometry and Material.

pub fn create_instanced_mesh<M: Into<Material>>(
    &mut self,
    geometry: &InstancedGeometry,
    material: M
) -> Mesh

Creates a Mesh using geometry that has already been loaded to the GPU.

See the module documentation in template for information on mesh instancing and its benefits.

Examples

use three::Geometry;

// Create geometry for a triangle.
let vertices = vec![
    [-0.5, -0.5, -0.5].into(),
    [0.5, -0.5, -0.5].into(),
    [0.0, 0.5, -0.5].into(),
];
let geometry = Geometry::with_vertices(vertices);

// Upload the triangle data to the GPU.
let upload_geometry = window.factory.upload_geometry(geometry);

// Create multiple meshes with the same GPU data and material.
let material = three::material::Basic {
    color: 0xFFFF00,
    map: None,
};
let first = window.factory.create_instanced_mesh(&upload_geometry, material.clone());
let second = window.factory.create_instanced_mesh(&upload_geometry, material.clone());
let third = window.factory.create_instanced_mesh(&upload_geometry, material.clone());

pub fn mesh_dynamic<M: Into<Material>>(
    &mut self,
    geometry: Geometry,
    material: M
) -> DynamicMesh

Create a new DynamicMesh with desired Geometry and Material.

pub fn mesh_instance(&mut self, template: &Mesh) -> Mesh

Create a Mesh sharing the geometry with another one. Rendering a sequence of meshes with the same geometry is faster. The material is duplicated from the template.

pub fn mesh_instance_with_material<M: Into<Material>>(
    &mut self,
    template: &Mesh,
    material: M
) -> Mesh

Create a Mesh sharing the geometry with another one but with a different material. Rendering a sequence of meshes with the same geometry is faster.

pub fn sprite(&mut self, material: Sprite) -> Sprite

Create new sprite from Material.

pub fn sprite_instance(&mut self, template: &Sprite) -> Sprite

Create a Sprite sharing the material with another one. Rendering a sequence of instanced sprites is much faster.

pub fn ambient_light(&mut self, color: Color, intensity: f32) -> Ambient

Create new AmbientLight.

pub fn directional_light(&mut self, color: Color, intensity: f32) -> Directional

Create new DirectionalLight.

pub fn hemisphere_light(
    &mut self,
    sky_color: Color,
    ground_color: Color,
    intensity: f32
) -> Hemisphere

Create new HemisphereLight.

pub fn point_light(&mut self, color: Color, intensity: f32) -> Point

Create new PointLight.

pub fn default_sampler(&self) -> Sampler

Create a Sampler with default properties.

The default sampler has Clamp as its horizontal and vertical wrapping mode and Scale as its filtering method.

pub fn sampler(
    &mut self,
    filter_method: FilterMethod,
    horizontal_wrap_mode: WrapMode,
    vertical_wrap_mode: WrapMode
) -> Sampler

Create new Sampler.

pub fn shadow_map(&mut self, width: u16, height: u16) -> ShadowMap

Create new ShadowMap.

pub fn basic_pipeline<P: AsRef<Path>>(
    &mut self,
    dir: P,
    name: &str,
    primitive: Primitive,
    rasterizer: Rasterizer,
    color_mask: ColorMask,
    blend_state: Blend,
    depth_state: Depth,
    stencil_state: Stencil
) -> Result<BasicPipelineState, PipelineCreationError>

Create a basic mesh pipeline using a custom shader.

pub fn ui_text<S: Into<String>>(&mut self, font: &Font, text: S) -> Text

Create new UI (on-screen) text. See Text for default settings.

pub fn audio_source(&mut self) -> Source

Create new audio source.

pub fn map_vertices<'a>(
    &'a mut self,
    mesh: &'a mut DynamicMesh
) -> Writer<'a, BackendResources, Vertex>

Map vertices for updating their data.

pub fn mix(&mut self, mesh: &DynamicMesh, shapes: &[(usize, f32)])

Interpolate between the shapes of a DynamicMesh.

pub fn load_font<P: AsRef<Path>>(&mut self, file_path: P) -> Font

Load TrueTypeFont (.ttf) from file.

Panics

Panics if I/O operations with file fails (e.g. file not found or corrupted)

pub fn load_font_karla(&mut self) -> Font

Load the Karla font

pub fn load_texture_from_memory(
    &mut self,
    width: u16,
    height: u16,
    pixels: &[u8],
    sampler: Sampler
) -> Texture<[f32; 4]>

Load texture from pre-loaded data.

pub fn load_texture<P: AsRef<Path>>(&mut self, path_str: P) -> Texture<[f32; 4]>

Load texture from file, with default Sampler. Supported file formats are: PNG, JPEG, GIF, WEBP, PPM, TIFF, TGA, BMP, ICO, HDR.

pub fn load_texture_with_sampler<P: AsRef<Path>>(
    &mut self,
    path_str: P,
    sampler: Sampler
) -> Texture<[f32; 4]>

Load texture from file, with custom Sampler. Supported file formats are: PNG, JPEG, GIF, WEBP, PPM, TIFF, TGA, BMP, ICO, HDR.

pub fn load_cubemap<P: AsRef<Path>>(
    &mut self,
    paths: &CubeMapPath<P>
) -> CubeMap<[f32; 4]>

Load cubemap from files. Supported file formats are: PNG, JPEG, GIF, WEBP, PPM, TIFF, TGA, BMP, ICO, HDR.

pub fn load_obj(&mut self, path_str: &str) -> (HashMap<String, Group>, Vec<Mesh>)

Load mesh from Wavefront Obj format.

pub fn load_audio<P: AsRef<Path>>(&self, path: P) -> Clip

Load audio from file. Supported formats are Flac, Vorbis and WAV.