diff --git a/assets/folder/tiled_relative_paths.tmx b/assets/folder/tiled_relative_paths.tmx new file mode 100644 index 0000000000000000000000000000000000000000..c330a5c94c22e617b32a19207c1ced46adb9df93 --- /dev/null +++ b/assets/folder/tiled_relative_paths.tmx @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="UTF-8"?> +<map version="1.8" tiledversion="1.8.2" orientation="orthogonal" renderorder="right-down" width="16" height="16" tilewidth="32" tileheight="32" infinite="0" nextlayerid="3" nextobjectid="1"> + <tileset firstgid="1" source="../tilesheet.tsx"/> + <layer id="1" name="Tile Layer 1" width="16" height="16"> + <data encoding="csv"> +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21, +21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21 +</data> + </layer> + <imagelayer id="2" name="image"> + <image source="../tilesheet.png" width="448" height="192"/> + </imagelayer> +</map> diff --git a/src/image.rs b/src/image.rs index 9220a93a2a30772260b150a286242c0ca4cfd865..b0df041fa607bd948ad1c8df8240c312cfd3a012 100644 --- a/src/image.rs +++ b/src/image.rs @@ -7,14 +7,63 @@ use crate::{error::TiledError, properties::Color, util::*}; /// A reference to an image stored somewhere within the filesystem. #[derive(Debug, PartialEq, Eq, Clone)] pub struct Image { - /// The filepath of the image. + /// The **uncanonicalized** filepath of the image, starting from the path given to load the file + /// this image is in. See the example for more details. /// /// ## Note /// The crate does not currently support embedded images (Even though Tiled /// does not allow creating maps with embedded image data, the TMX format does; [source]) /// + /// Currently, the crate is not prepared to handle anything but OS paths. Using VFS is a hard + /// task that involves a lot of messy path manipulation. [Tracking issue] + /// /// [source]: https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#image + /// [Tracking issue]: https://github.com/mapeditor/rs-tiled/issues/37 + /// + /// ## Example + /// ``` + /// use std::path::Path; + /// use std::fs::File; + /// use tiled::*; + /// + /// # fn main() -> Result<(), Box<dyn std::error::Error>> { + /// let map = Map::parse_file( + /// "assets/folder/tiled_relative_paths.tmx", + /// &mut FilesystemResourceCache::new(), + /// )?; + /// + /// let image_layer = match map + /// .layers() + /// .find(|layer| layer.name() == "image") + /// .unwrap() + /// .layer_type() + /// { + /// LayerType::ImageLayer(layer) => layer, + /// _ => panic!(), + /// }; + /// + /// // Image layer has an image with the source attribute set to "../tilesheet.png" + /// // Given the information we gave to the `parse_file` function, the image source should be + /// // "assets/folder/../tilesheet.png". The filepath is not canonicalized. + /// let image_source = &image_layer.image().unwrap().source; + /// + /// assert_eq!( + /// image_source, + /// Path::new("assets/folder/../tilesheet.png") + /// ); + /// + /// // If you are using the OS's filesystem, figuring out the real path of the image is as easy + /// // as canonicalizing the path. If you are using some sort of VFS, this task is much harder + /// // since std::path is meant to be used with the OS. This will be fixed in the future! + /// let image_source = image_source.canonicalize()?; + /// assert!(File::open(image_source).is_ok()); + /// # Ok(()) + /// # } + /// ``` + /// Check the assets/tiled_relative_paths.tmx file at the crate root to see the structure of the + /// file this example is referring to. // TODO: Embedded images + // TODO: Figure out how to serve crate users paths in a better way pub source: PathBuf, /// The width in pixels of the image. pub width: i32,