Particles: AddMovingParticleToBuffer

       Name: AddMovingParticleToBuffer                               [Show more]
       Type: Subroutine
   Category: Particles
    Summary: Add a moving particle to the particle data buffer, adding a random
             element to its velocity and lifespan counter
  Deep dive: Particles and particle clouds
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * AddExhaustParticleToBuffer calls AddMovingParticleToBuffer


 Arguments:

   (R0, R1, R2)                     Particle coordinate

   (R3, R4, R5)                     Particle velocity

   R6                               Particle lifespan counter (i.e. how many
                                    iterations around the main loop before the
                                    particle expires)

   R7                               Particle flags:

                                      * Bits 0-7   = particle colour
                                      * Bit 16 set = colour fades white to red
                                      * Bit 17 set = particle is a rock
                                      * Bit 18 set = splash on impact with sea
                                      * Bit 19 set = bounce on hitting ground
                                      * Bit 20 set = apply gravity to particle
                                      * Bit 21 set = can destroy objects
                                      * Bit 23 set = splash size (big when set)
                                      * Bit 24 set = explode on hitting ground

   R8                               Magnitude of the random element that's added
                                    to the velocity, with a larger figure giving
                                    a smaller random element; the actual range
                                    is +/- 2^(32 - R8)

   R9                               Magnitude of the random element that's added
                                    to the particle lifespan, with a larger
                                    figure giving a smaller random element; the
                                    actual range is 0 to 2^(32 - R9)

   Stack                            Contains a value to restore into R8 at the
                                    end, and the return address


.AddMovingParticleToBuffer

 STMFD   R13!, {R0-R1}              \ Store R0 and R1 on the stack so we can
                                    \ restore them after the following

                                    \ We now add a random signed element to the
                                    \ particle velocity in (R3, R4, R5), with
                                    \ the scale of the random element determined
                                    \ by R8 (so a larger R8 adds a smaller
                                    \ random element to the velocity)

 BL      GetRandomNumbers           \ Set R0 and R1 to random numbers

 ADD     R3, R3, R0, ASR R8         \ Set R3 = R3 + R0 >> R8
                                    \
                                    \ We keep the sign in R0, so this can either
                                    \ increase or decrease R3

 BL      GetRandomNumbers           \ Set R0 and R1 to random numbers

 ADD     R4, R4, R0, ASR R8         \ Set R4 = R4 + R0 >> R8
                                    \
                                    \ We keep the sign in R0, so this can either
                                    \ increase or decrease R4

 BL      GetRandomNumbers           \ Set R0 and R1 to random numbers

 ADD     R5, R5, R0, ASR R8         \ Set R5 = R5 + R0 >> R8
                                    \
                                    \ We keep the sign in R0, so this can either
                                    \ increase or decrease R5

                                    \ We now add a random positive element to
                                    \ the particle's lifespan counter in R6,
                                    \ with the scale determined by R9 (so a
                                    \ larger R9 adds a smaller random element
                                    \ to the particle's lifespan)

 BL      GetRandomNumbers           \ Set R0 and R1 to random numbers

 ADD     R6, R6, R0, LSR R9         \ Set R6 = R6 + R0 >> R9
                                    \
                                    \ We do not keep the sign in R0, so the
                                    \ addition is always positive

 LDMFD   R13!, {R0-R1}              \ Retrieve the values of R0 and R1 that we
                                    \ stored above