Allow for custom particle textures

Author: SteelFill

Source/Documentation/Manual/physics.rst

@@ -2471,6 +2471,9 @@ the one shown below::
         ORTSMaxParticles ( 2500 )
         ORTSRateMultiplier ( 1.0 )
         ORTSUseChaoticRandomization ( false )
+
+        ORTSGraphic ( "smokemain.ace" )
+        ORTSGraphicAtlasLayout ( 4 4 )
     )
 
 The code block consists of the following elements:
@@ -2499,6 +2502,8 @@ The code block consists of the following elements:
    single: ORTSMaxParticles
    single: ORTSRateMultiplier
    single: ORTSUseChaoticRandomization
+   single: ORTSGraphic
+   single: ORTSGraphicAtlasLayout
 
 After including these settings, additional *optional* parameters unique to OR can
 be included to further customize effect emitters:
@@ -2507,7 +2512,7 @@ be included to further customize effect emitters:
   in the right/left, up/down, and front/back emission location of a particle (default units
   are meters). Useful for non-circular exhaust ports, as it allows one particle emitter
   to be used to spawn particles from an area, rather than a single point. Note that
-  ``ORTSPositionVariation ( 1m 0m 0m )`` would allow particles to emit 1 meter right and
+  ``ORTSPositionVariation ( x y z )`` would allow particles to emit 1 meter right and
   1 meter left of the initial position, for a total variation of 2 meters. Similar is
   true of all other parameters related to randomness, the total variation is double what's
   specified. Feature is disabled by default.
@@ -2602,6 +2607,21 @@ be included to further customize effect emitters:
   randomziation algorithm changes the random values by a small amount for each iteration. The "chaotic"
   algorithm tends to make exhaust that is more spread out and discontinuous, which may be desireable in
   some cases.
+- ``ORTSGraphic ( "tex" )`` -- Gives the name and path to the texture that should be used to render
+  particles from this emitter. The default texture is "smokemain.ace" for steam-type emitters and
+  "dieselsmoke.ace" for diesel-type emitters. If the texture cannot be found from the engine's/wagon's
+  folder, then the ``GLOBAL\TEXTURES`` folder is checked, and if the texture is not there the ``Content``
+  folder included with OR is checked. Allowed texture formats are ``.png, .jpg, .bmp, .gif, .ace, or .dds``.
+  A path to a texture can also be used, such as ``ORTSGraphic ( "..\\SmokeTextures\\steam.dds" )``, to search
+  for textures not in the same folder as the engine or wagon.
+- ``ORTSGraphicAtlasLayout ( w h )`` -- Particle textures generally include multiple sprites in a single file
+  to allow for randomization of each particle's appearance. In MSTS, this was a sprite atlas 4 wide and 4 high,
+  for a total of 16 variations on the particle graphic. When using custom particle textures, it may be desired
+  to use a custom sprite sheet that is not 4x4, in which case the atlas layout can be set by ``ORTSGraphicAtlasLayout``.
+  For example, a sprite sheet with 4 variations on the particle texture all in a row (4x1) can be represented by
+  ``ORTSGraphicAtlasLayout ( 4 1 )``. Note that each sprite should be a perfect square as each particle is
+  rendered as a square. Rectangular textures will be stretched/squished. Do not change the atlas setting unless you
+  are certain of the texture used, as improper settings will be very aesthetically unpleasing.
 
 
 .. index::
@@ -2621,7 +2641,7 @@ matter:
     )
 
 - ``ORTSPosition ( x y z )`` -- defines the width, height, length location of the emitter (in meters by default)
-- ``ORTSInitialVelocity ( x y z )`` -- defines the right, up, forward components of emission direction
+- ``ORTSInitialVelocity ( x y z )`` -- defines the (+/-) right/left, up/down, forward/backward components of emission direction
   (unitless, the particle speed is multiplied by this vector to determine the 3D velocity of particles.
   Speed can be divided by inserting values less than 1, or multiplied by inserting values greater than 1.)
 - And ``ORTSParticleDiameter ( d )`` -- gives the nozzle width (in meters by default), which sets the initial

Source/Orts.Simulation/Simulation/RollingStocks/MSTSWagon.cs

@@ -4610,7 +4610,7 @@ public class ParticleEmitterData
 
         public float SpeedLimitMpS = 150.0f;
 
-        public float NozzleDiameterM;
+        public float NozzleDiameterM = 0.1f;
         public float NozzleAreaM2 = -1; // If left at -1, will be initialized later
 
         public float RateFactor = 1.0f;
@@ -4628,6 +4628,10 @@ public class ParticleEmitterData
 
         public bool ChaoticRandomization = false; // Changes the style of RNG used for particle motion
 
+        public string Graphic;
+        public int AtlasWidth = 4;
+        public int AtlasHeight = 4;
+
         public ParticleEmitterData(STFReader stf)
         {
             stf.MustMatch("(");
@@ -4674,6 +4678,13 @@ public ParticleEmitterData(STFReader stf)
                 new STFReader.TokenProcessor("ortsmaxparticles", ()=>{ MaxParticles = stf.ReadIntBlock(null); }),
                 new STFReader.TokenProcessor("ortsratemultiplier", ()=>{ RateFactor = stf.ReadFloatBlock(STFReader.UNITS.None, null); }),
                 new STFReader.TokenProcessor("ortsusechaoticrandomization", ()=>{ ChaoticRandomization = stf.ReadBoolBlock(true); }),
+                new STFReader.TokenProcessor("ortsgraphic", ()=>{ Graphic = stf.ReadStringBlock(null); }),
+                new STFReader.TokenProcessor("ortsgraphicatlaslayout", ()=>{
+                    stf.MustMatch("(");
+                    AtlasWidth = Math.Max(stf.ReadInt(null), 1);
+                    AtlasHeight = Math.Max(stf.ReadInt(null), 1);
+                    stf.SkipRestOfBlock();
+                }),
             });
         }
     }

Source/RunActivity/Content/ParticleEmitterShader.fx

@@ -33,13 +33,14 @@ float emitSize;
 float2 cameraTileXY;
 float currentTime;
 
-static float2 texCoords[4] = { float2(0, 0), float2(0.25f, 0), float2(0.25f, 0.25f), float2(0, 0.25f) };
+static float2 texCoords[4] = { float2(0, 0), float2(1.0f, 0), float2(1.0f, 1.0f), float2(0, 1.0f) };
 static float3 offsets[4] = { float3(-0.5f, 0.5f, 0), float3(0.5f, 0.5f, 0), float3(0.5f, -0.5f, 0), float3(-0.5f, -0.5f, 0) };
 
 float4 Fog;
 
 // Textures
 texture particle_Tex;
+float2 texAtlasSize;
 
 // Texture settings
 sampler ParticleSamp = sampler_state
@@ -142,9 +143,11 @@ VERTEX_OUTPUT VSParticles(in VERTEX_INPUT In)
 
 	Out.TexCoord = texCoords[vertIdx];
 	float texAtlasPosition = In.TileXY_Vertex_ID.w;
-	int atlasX = texAtlasPosition % 4;
-	int atlasY = texAtlasPosition / 4;
-	Out.TexCoord += float2(0.25f * atlasX, 0.25f * atlasY);
+	int atlasX = texAtlasPosition % texAtlasSize.x;
+	int atlasY = texAtlasPosition / texAtlasSize.y;
+    Out.TexCoord.x /= texAtlasSize.x;
+    Out.TexCoord.y /= texAtlasSize.y;
+	Out.TexCoord += float2(atlasX / texAtlasSize.x, atlasY / texAtlasSize.y);
 
 	Out.Color_Age.rgb = In.Color_Random.rgb;
 

Source/RunActivity/Viewer3D/Materials.cs

@@ -65,12 +65,14 @@ public Texture2D Get(string path, Texture2D defaultTexture, bool required = fals
                 return defaultTexture;
 
             path = path.ToLowerInvariant();
+            var ext = Path.GetExtension(path);
+
             if (!Textures.ContainsKey(path))
             {
                 try
                 {
                     Texture2D texture;
-                    if (Path.GetExtension(path) == ".dds")
+                    if (ext == ".dds")
                     {
                         if (File.Exists(path))
                         {
@@ -89,10 +91,10 @@ public Texture2D Get(string path, Texture2D defaultTexture, bool required = fals
                             else return defaultTexture;
                         }
                     }
-                    else if (Path.GetExtension(path) == ".ace")
+                    else if (ext == ".ace")
                     {
                         var alternativeTexture = Path.ChangeExtension(path, ".dds");
-                        
+
                         if (File.Exists(alternativeTexture))
                         {
                             DDSLib.DDSFromFile(alternativeTexture, GraphicsDevice, true, out texture);
@@ -145,7 +147,30 @@ Texture2D invalid()
                         }
                     }
                     else
-                        return defaultTexture;
+                    {
+                        using (var stream = File.OpenRead(path))
+                        {
+                            if (ext == ".gif" || ext == ".jpg" || ext == ".png")
+                                texture = Texture2D.FromStream(GraphicsDevice, stream);
+                            else if (ext == ".bmp")
+                            {
+                                using (var image = System.Drawing.Image.FromStream(stream))
+                                {
+                                    using (var memoryStream = new MemoryStream())
+                                    {
+                                        image.Save(memoryStream, System.Drawing.Imaging.ImageFormat.Png);
+                                        memoryStream.Seek(0, SeekOrigin.Begin);
+                                        texture = Texture2D.FromStream(GraphicsDevice, memoryStream);
+                                    }
+                                }
+                            }
+                            else
+                            {
+                                Trace.TraceWarning("Unsupported texture format: {0}", path);
+                                return defaultTexture;
+                            }
+                        }
+                    }
 
                     Textures.Add(path, texture);
                     return texture;

Source/RunActivity/Viewer3D/ParticleEmitter.cs

@@ -22,11 +22,13 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
 using Microsoft.Xna.Framework;
 using Microsoft.Xna.Framework.Graphics;
-using ORTS.Common;
 using Orts.Simulation.RollingStocks;
 using Orts.Viewer3D.RollingStock;
+using ORTS.Common;
 
 namespace Orts.Viewer3D
 {
@@ -39,6 +41,7 @@ public class ParticleEmitterViewer
         public readonly float ParticleVolumeM3 = 0.001f;
         public readonly ParticleEmitterPrimitive Emitter;
 
+        public string TexturePath;
         ParticleEmitterMaterial Material;
 
 #if DEBUG_EMITTER_INPUT
@@ -66,15 +69,40 @@ public ParticleEmitterViewer(Viewer viewer, ParticleEmitterData data, MSTSWagonV
             // Particles expand over time, this is just the initial volume, useful for calculating initial velocity
             ParticleVolumeM3 = 4.0f / 3.0f * MathHelper.Pi * ((EmitterData.NozzleDiameterM * EmitterData.NozzleDiameterM * EmitterData.NozzleDiameterM) / 8.0f);
             Emitter = new ParticleEmitterPrimitive(this, data, car, worldPosition);
+
+            if (!String.IsNullOrEmpty(EmitterData.Graphic))
+                TexturePath = EmitterData.Graphic;
 #if DEBUG_EMITTER_INPUT
             EmitterID = ++EmitterIDIndex;
             InputCycle = Viewer.Random.Next(InputCycleLimit);
 #endif
-        }
+            }
 
-        public void Initialize(string textureName)
+        public void Initialize(string defaultTextureName)
         {
-            Material = (ParticleEmitterMaterial)Viewer.MaterialManager.Load("ParticleEmitter", textureName);
+            bool customTexture = false;
+
+            if (!String.IsNullOrEmpty(TexturePath))
+                customTexture = true;
+            else
+                TexturePath = defaultTextureName;
+
+            // Texture location preference is eng/wag folder -> MSTS GLOBAL\TEXTURES folder -> OR CONTENT folder
+            if (File.Exists(Path.Combine(Path.GetDirectoryName(Emitter.CarViewer.Car.WagFilePath), TexturePath)))
+                TexturePath = Path.Combine(Path.GetDirectoryName(Emitter.CarViewer.Car.WagFilePath), TexturePath);
+            else if (File.Exists(Path.Combine(Viewer.Simulator.BasePath + @"\GLOBAL\TEXTURES\", TexturePath)))
+                TexturePath = Path.Combine(Viewer.Simulator.BasePath + @"\GLOBAL\TEXTURES\", TexturePath);
+            else if (customTexture && File.Exists(Path.Combine(Viewer.ContentPath, TexturePath)))
+                TexturePath = Path.Combine(Viewer.ContentPath, TexturePath);
+            else // Fall back to default texture in CONTENT folder
+            {
+                TexturePath = Path.Combine(Viewer.ContentPath, defaultTextureName);
+
+                if (customTexture)
+                    Trace.TraceWarning("Could not find particle graphic {0} at {1}", TexturePath, Path.Combine(Path.GetDirectoryName(Emitter.CarViewer.Car.WagFilePath), TexturePath));
+            }
+
+            Material = (ParticleEmitterMaterial)Viewer.MaterialManager.Load("ParticleEmitter", TexturePath);
         }
 
         /// <summary>
@@ -335,6 +363,8 @@ struct ParticleVertex
         internal float ParticleDuration;
         internal Color ParticleColor;
 
+        internal int SpriteCount;
+
         internal float CompressionFactor = 1.0f;
 
         internal WorldPosition WorldPosition;
@@ -373,6 +403,8 @@ public ParticleEmitterPrimitive(ParticleEmitterViewer particleViewer, ParticleEm
             ParticleDuration = 3;
             ParticleColor = Color.White;
 
+            SpriteCount = EmitterData.AtlasWidth * EmitterData.AtlasHeight;
+
             CarViewer = car;
             WorldPosition = worldPosition;
 
@@ -548,6 +580,7 @@ public void Update(float currentTime, ElapsedTime elapsedTime)
                     rotY.Normalize();
 
                     float initialSpeed = XNAInitialVelocity.Length();
+                    Vector3 carVelocity = new Vector3(CarViewer.Velocity[0], CarViewer.Velocity[1], -CarViewer.Velocity[2]);
 
                     float time = currentTime - elapsedTime.ClockSeconds;
 
@@ -559,12 +592,11 @@ public void Update(float currentTime, ElapsedTime elapsedTime)
 
                         int nextFreeParticle = (FirstFreeParticle + 1) % EmitterData.MaxParticles;
                         int vertex = FirstFreeParticle * VerticesPerParticle;
-                        int texture = Viewer.Random.Next(16); // Randomizes emissions.
+                        int texture = Viewer.Random.Next(SpriteCount); // Randomizes particle texture to any texture on the sheet.
                                                               // Alpha value of color is just a random number, not used (maybe allow for alpha changes?)
                         Color color_Random = new Color(ParticleColor.R, ParticleColor.G, ParticleColor.B, (int)((float)Viewer.Random.NextDouble() * 255f));
 
                         Vector3 position = EmitterData.PositionM;
-                        Vector3 carVelocity = new Vector3(CarViewer.Velocity[0], CarViewer.Velocity[1], -CarViewer.Velocity[2]);
 
                         Vector3 initialVelocity = XNAInitialVelocity;
                         Vector3 finalVelocity = XNAFinalVelocity;
@@ -764,6 +796,7 @@ public override void Render(GraphicsDevice graphicsDevice, IEnumerable<RenderIte
                     var emitter = (ParticleEmitterPrimitive)item.RenderPrimitive;
                     shader.EmitSize = emitter.EmitSize;
                     shader.Texture = Texture;
+                    shader.TextureAtlasSizeXY = new Vector2(emitter.EmitterData.AtlasWidth, emitter.EmitterData.AtlasHeight);
                     shader.SetMatrix(Matrix.Identity, ref XNAViewMatrix, ref XNAProjectionMatrix);
                     ShaderPasses.Current.Apply();
                     item.RenderPrimitive.Draw(graphicsDevice);

Source/RunActivity/Viewer3D/RollingStock/MSTSDieselLocomotiveViewer.cs

@@ -41,7 +41,7 @@ public MSTSDieselLocomotiveViewer(Viewer viewer, MSTSDieselLocomotive car)
             // Now all the particle drawers have been setup, assign them textures based
             // on what emitters we know about.
 
-            string dieselTexture = viewer.Simulator.BasePath + @"\GLOBAL\TEXTURES\dieselsmoke.ace";
+            string dieselTexture = "dieselsmoke.ace";
 
 
             // Diesel Exhaust

Source/RunActivity/Viewer3D/RollingStock/MSTSSteamLocomotiveViewer.cs

@@ -80,7 +80,7 @@ public MSTSSteamLocomotiveViewer(Viewer viewer, MSTSSteamLocomotive car)
         {
             // Now all the particle drawers have been setup, assign them textures based
             // on what emitters we know about.
-            string steamTexture = viewer.Simulator.BasePath + @"\GLOBAL\TEXTURES\smokemain.ace";
+            string steamTexture = "smokemain.ace";
 
             foreach (var emitter in ParticleDrawers)
             {

Source/RunActivity/Viewer3D/RollingStock/MSTSWagonViewer.cs

@@ -115,8 +115,8 @@ public MSTSWagonViewer(Viewer viewer, MSTSWagon car)
             : base(viewer, car)
         {
 
-            string steamTexture = viewer.Simulator.BasePath + @"\GLOBAL\TEXTURES\smokemain.ace";
-            string dieselTexture = viewer.Simulator.BasePath + @"\GLOBAL\TEXTURES\dieselsmoke.ace";
+            string steamTexture = "smokemain.ace";
+            string dieselTexture = "dieselsmoke.ace";
 
             // Particle Drawers called in Wagon so that wagons can also have steam effects.
             ParticleDrawers = (

Source/RunActivity/Viewer3D/Shaders.cs

@@ -468,6 +468,7 @@ public class ParticleEmitterShader : Shader
         EffectParameter wvp;
         EffectParameter invView;
         EffectParameter texture;
+        EffectParameter textureAtlasSize;
         EffectParameter lightVector;
         EffectParameter fog;
 
@@ -486,6 +487,11 @@ public Texture2D Texture
             set { texture.SetValue(value); }
         }
 
+        public Vector2 TextureAtlasSizeXY
+        {
+            set { textureAtlasSize.SetValue(value); }
+        }
+
         public float EmitSize
         {
             set { emitSize.SetValue(value); }
@@ -505,6 +511,7 @@ public ParticleEmitterShader(GraphicsDevice graphicsDevice)
             invView = Parameters["invView"];
             tileXY = Parameters["cameraTileXY"];
             texture = Parameters["particle_Tex"];
+            textureAtlasSize = Parameters["texAtlasSize"];
             lightVector = Parameters["LightVector"];
             fog = Parameters["Fog"];
         }