Damian/Puma_Viewer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Apertura del repositorio

Browse Source
This commit is contained in:
Damian
2025-05-24 18:09:39 -03:00
parent 76e6359dad
commit d883ddd0d0
35253 changed files with 2891973 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/FS_PR_GUIDELINES.md
+63
View File
@@ -0,0 +1,63 @@
# Firestorm Pull Request Guidelines
Thank you for submitting code to Firestorm; we will review it and merge or provide feedback in due course.
We have written this guide to help you contribute code that meets our needs. It will hopefully reduce the number of iterations required before we can merge the code.
1. **Descriptive Title**:
   - Use a clear and descriptive title for the PR.
1. **Related Issues**:
   - Reference any related issues or pull requests by including the JIRA number and description in the commit message header (e.g., `[FIRE-12345] When I click, my head falls off` or `[FIRE-12345] prevent click detaching head`).
1. **Description**:
   - Provide a detailed description of the changes. Explain why the changes are necessary and what problem they solve. If a JIRA is associated with the change, there is no need to duplicate that, but we would appreciate a summary and explanation of the fix.
1. **Comment tags (important)**:
   - We use comments to preserve the original upstream (LL) code when making modifications; this allows the person merging future code updates to see both the original code from LL and any new updates and then use those to determine whether the FS-specific changes need to be updated and reviewed.
If you are modifying LL code, we need the LL code preserved in a comment.
For example:
```c++
    int buggy_code = TRUE;
    LL_WARN() << "This code is buggy" << LL_ENDL;
```
Would become:
```c++
    // <FS> [FIRE-999] Fix the buggy code
    // int buggy_code = TRUE;
    // LL_WARN() << "This code is buggy" << LL_ENDL;
    bool fixed_code = true;
    LL_DEBUG() << "I fixed this" << LL_ENDL;
    // </FS>
```
Note: You can tag them with your initials, e.g. `<FS:YI>` or a short unique tag (shorter is better)
If you add new code, the same rules apply, but there is nothing to comment out.
This is done so that when LL updates the original code, we can see what the original code was doing, what their changes do, and how that relates to the changes that we applied on top.
A single line change can use the shorthand `<FS:YI/>`:
```c++
    bool break_stuff=true;
```
Could be fixed as follows:
```c++
    bool break_stuff=false; // <FS:Beq/> [FIRE-23456] don't break stuff.
```
The Comment tags are only required when changing code maintained upstream. If the code you are changing is in an FS-created file, RLV code, OpenSim-only code, etc., then we do not need the comments.
If the code you are changing is already inside an `//<FS>` comment block, then there is no need to add a new block, but do try to make sure that any comments align with the updates you make.
5. **Testing**:
   - Include details on how the changes should be tested. Describe the testing environment and any steps needed to verify the changes.
1. **Documentation**:
   - If the change includes a new feature, it would be beneficial to suggest how we should update the FS Wiki pages to help users understand the feature
Thank you for your contribution!
doc/LGPL-license.txt
Executable
+502
View File
@@ -0,0 +1,502 @@
GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence
the version number 2.1.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it. You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
GNU LESSER GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (1) uses at run time a
copy of the library already present on the user's computer system,
rather than copying library functions into the executable, and (2)
will operate properly with a modified version of the library, if
the user installs one, as long as the modified version is
interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.
<signature of Ty Coon>, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!
doc/LICENSE-logos.txt
Executable
+23
View File
@@ -0,0 +1,23 @@
COPYRIGHT AND PERMISSION NOTICE
Second Life(TM) Viewer Artwork. Copyright (C) 2008 Linden Research, Inc.
Linden Research, Inc. ("Linden Lab") licenses the Second Life viewer
artwork and other works in the files distributed with this Notice under
the Creative Commons Attribution-Share Alike 3.0 License, available at
http://creativecommons.org/licenses/by-sa/3.0/legalcode. For the license
summary, see http://creativecommons.org/licenses/by-sa/3.0/.
Notwithstanding the foregoing, all of Linden Lab's trademarks, including
but not limited to the Second Life brand name and Second Life Eye-in-Hand
logo, are subject to our trademark policy at
http://secondlife.com/corporate/brand/trademark/.
If you distribute any copies or adaptations of the Second Life viewer
artwork or any other works in these files, you must include this Notice
and clearly identify any changes made to the original works. Include
this Notice and information where copyright notices are usually included,
for example, after your own copyright notice acknowledging your use of
the Second Life viewer artwork, in a text file distributed with your
program, in your application's About window, or on a credits page for
your work.
doc/LICENSE-source.txt
Executable
+33
View File
@@ -0,0 +1,33 @@
Source code
========
The license for the source code in this distribution should be clearly
marked on each source file. Unless otherwise specified, the source
code in this distribution ("Source Code") is provided by Linden Lab to
you under the terms of the GNU Lesser General Public License, version 2.1
("LGPL"), unless you have obtained a separate licensing agreement
("Other License"), formally executed by you and Linden Lab. Terms of
the GPL can be found in doc/LGPL-license.txt in this distribution, or
online at
https://wiki.secondlife.com/wiki/Linden_Lab_Official:GNU_Lesser_General_Public_License,_version_2.1
By copying, modifying or distributing this software, you acknowledge
that you have read and understood your obligations described above,
and agree to abide by those obligations.
ALL LINDEN LAB SOURCE CODE IS PROVIDED "AS IS." LINDEN LAB MAKES NO
WARRANTIES, EXPRESS, IMPLIED OR OTHERWISE, REGARDING ITS ACCURACY,
COMPLETENESS OR PERFORMANCE.
Logos and trademarks
==============
"Second Life" and "Linden Lab" are registered trademarks of Linden
Research, Inc. Other trademarks include (but are not limited to): the
names Linden and Linden Research, as well as the Linden Lab Hexagon
Design and the Second Life Hand Design logos.
Use of logos and trademarks are subject to the Linden Lab trademark
policy, available at:
http://secondlife.com/corporate/trademark/
doc/building_linux.md
+277
View File
@@ -0,0 +1,277 @@
# Build instructions for Linux
> [!WARNING]
> Please note that we do not give support for compiling the viewer on your own. However, there is a self-compilers group in Second Life that can be joined to ask questions related to compiling the viewer: [Firestorm Self Compilers](https://tinyurl.com/firestorm-self-compilers)
This procedure is based on discussions with the Firestorm Linux development team and is the only one recommended for Firestorm for Linux. System requirements are:
- Ubuntu 22.04 LTS (x86_64) - fully upgraded (this is also now the minimum requirement for running the viewer).
- 16GB or more RAM ([Low Memory Caution](#common-issuesbugsglitches-and-solutions))
- 64GB hard drive space
- 4 or more core CPU (you could get by with 2 cores, but the process will take much longer)
- GCC 11 compiler (which is the default version on Ubuntu 22.04 LTS)
It is recommended that you use a virtual machine for compiling, ensuring the guest can meet the hardware requirements.
This procedure may or may not work on other Linux distributions (or you might need to adjust some of the package names to suit the distribution you are using).
> [!WARNING]
> A system with a glibc version of at least 2.34 is required (Ubuntu 22.04 LTS meets this requirement)
> Building on a system with a glibc version older than 2.34 will likely result in linker errors.
> [!IMPORTANT]
> Only 64 bit builds are possible - 32 bit support was dropped quite some time ago.
## Establish your programming environment
This only needs to be done once.
### Create your source tree
Typically, Linux source code is stored in a src directory in your home directory. So: `mkdir ~/src`
### Install required packages
A few packages must be installed on the build system. Some may already be installed:
| | | | | | |
| --------------- | ---------------- | ------------- | ------------------ | ---------------- | ------ |
| libgl1-mesa-dev | libglu1-mesa-dev | libpulse-dev | build-essential | python3-pip | git |
| libssl-dev | libxinerama-dev | libxrandr-dev | libfontconfig-dev | libfreetype6-dev | gcc-11 |
| cmake | | | | | |
```
sudo apt install libgl1-mesa-dev libglu1-mesa-dev libpulse-dev build-essential python3-pip git libssl-dev libxinerama-dev libxrandr-dev libfontconfig-dev libfreetype6-dev gcc-11 cmake
```
### Install Autobuild
Autobuild is a Linden Lab resource that does all the hard work.
You can install it using the same versions as our automated builds as follows:
```
sudo pip3 install --upgrade pip
pip install -r requirements.txt
```
Check Autobuild version to be "autobuild 3.9.3" or higher: `autobuild --version`
## Download the source code
There are two required repositories, the viewer itself and the build variables. An optional third repository is used to configure and package FMOD Studio.
### Clone the viewer
```
cd ~/src
git clone https://github.com/FirestormViewer/phoenix-firestorm.git
```
This will create a folder called phoenix-firestorm and add all the source files. If you desire, you can choose a different folder name by adding the name to the end of the command:
```
git clone https://github.com/FirestormViewer/phoenix-firestorm.git NewDestinationDirectory
```
The rest of this document will assume the default directory, `phoenix-firestorm`
### Clone the Autobuild build variables
Autobuild uses a separate file to control compiler options, switches, and the like for different configurations.
```
cd ~/src
git clone https://github.com/FirestormViewer/fs-build-variables.git
```
### Create FMOD Studio package (optional)
Although not required, including FMOD Studio in your build will improve your audio-based experience.
```
cd ~/src
git clone https://github.com/FirestormViewer/3p-fmodstudio.git
cd ~/src/3p-fmodstudio
```
Open the file called `build-cmd.sh` and look at the fifth line down, it begins with `FMOD_VERSION`. This is the version of the API you need to download.
The FMOD Studio API can be downloaded [here](https://www.fmod.com) (requires creating a free account to access the download section).
Click the button representing the version you're after, then click the Download link for the Linux file.
> [!IMPORTANT]
> Make sure to download the FMOD Studio API and not the FMOD Studio Tool!
Copy that file to the `~/src/3p-fmodstudio` directory.
```
export AUTOBUILD_VARIABLES_FILE=$HOME/src/fs-build-variables/variables
autobuild build -A 64 --all
autobuild package -A 64 --results-file result.txt
```
Near the end of the output you will see the package name written, similar to:
```
wrote !/home/username/src/3p-fmodstudio/fmodstudio-2.01.02-linux64-202161533.tar.bz2
```
Additionally, a file `result.txt` has been created containing the md5 hash value of the package file, which you will need in the next steps.
```
cd ~/src/phoenix-firestorm
```
Copy the FMOD Studio path and md5 value from the package process into this command:
```
autobuild installables edit fmodstudio platform=linux64 hash=<md5 value> url=file:///<fmodstudio path>
```
For example:
```
autobuild installables edit fmodstudio platform=linux64 hash=c3f696412ef74f1559c6d023efe3a087 url=file:///!/src/3p-fmodstudio/fmodstudio-2.00.07-linux64-200912220.tar.bz2
```
> [!NOTE]
> Having modified autobuild.xml would require it be restored before trying to fetch any new commits or more especially if you push a commit. This can be done with `git reset --hard && git remote update`
## Configure and build
### Configuring the viewer
Start by initializing the variables
```
export AUTOBUILD_VARIABLES_FILE=$HOME/src/fs-build-variables/variables
```
You can add that to `~/.bashrc` or `~/.profile` so they execute automatically, or execute them before you run autobuild.
```
cd ~/src/phoenix-firestorm
autobuild configure -A 64 -c ReleaseFS_open
```
This will set up to compile with all defaults and without non-default libraries. It will fetch any additional necessary libraries.
Available premade firestorm-specific build targets:
```
ReleaseFS (includes KDU, FMOD)
ReleaseFS_open (no KDU, no FMOD)
RelWithDebInfoFS_open (no KDU, no FMOD)
```
### Configuration Switches
There are a number of switches you can use to modify the configuration process. The name of each switch is followed by its type and then by the value you want to set.
- **LL_TESTS** (bool) controls if the tests are compiled and run. There are quite a lot of them so excluding them is recommended unless you have some reason to need one or more of them.
- **clean** will cause autobuild to remove any previously compiled objects and fetched packages. It can be useful if you need to force a reload of all packages
- **package** will result in a bzip2 archive of the completed viewer. Enabled by default, you would have to use **-DPACKAGE:BOOL=Off** to disable it
- **chan** will set a unique channel (and the name) for the viewer, appending whatever is defined to "Firestorm-". By default, the channel is "private" followed by your computer's name.
- **fmodstudio** will tell autobuiild to use the FmodStudio package when compiling.
Most switches start with a double-dash (\--). And if you use any switches you must enclose them with a double-dash at the start and an optional double-dash at the end.
> [!TIP]
> **OFF** and **NO** are the same as **FALSE**; anything else is considered to be **TRUE**
Examples:
```
autobuild configure -A 64 -c ReleaseFS_open -- -DLL_TESTS:BOOL=FALSE
autobuild configure -A 64 -c ReleaseFS_open -- --clean
autobuild configure -A 64 -c ReleaseFS_open -- --fmodstudio
autobuild configure -A 64 -c ReleaseFS_open -- --chan="MyBuild"
```
In the last example, the channel and resulting viewer name would be "Firestorm-MyBuild".
The first time you configure, several additional files will be downloaded from Firestorm and Second Life sources. These are mostly binary packages maintained outside the viewer development itself. And if you use the `--clean` switch, you will re-download them all.
## Compiling the viewer
```
autobuild build -A 64 -c ReleaseFS_open
```
Be sure to use the fmodstudio and chan switches again.
Compiling can take quite a bit of time depending on your computer's processing power.
> [!NOTE]
> It is possible to use autobuild to do both the configure step (only needed once) and the build step with one command (`autobuild build -A 64 -c ReleaseFS_open -- --clean [more switches]`). For clarity, they are mentioned separately.
> [!TIP]
> When using the --package switch you can set the XZ_DEFAULTS variable to -T0 to use all available CPU cores to create the .tar.xz file. This can significantly reduce the time needed to create the archive, but it will use a lot more memory. For example:
> ```
> export XZ_DEFAULTS="-T0"
> autobuild build -A64 -c ReleaseFS_open -- --package
> ```
### Copy out of the guest
If you build the viewer using a virtual machine (guest), you will need to copy the viewer files over to your host or to a different machine in order to use the viewer. Your guest may not have sufficient resources to run the viewer. The rsync program can make copying easy and accurate. And if you build the viewer again, the options included in the command example will cause rsync to only copy the new files, cutting down on the time needed to copy.
The build process created a ready-to-use viewer as well as a compressed archive. The archive can be copied or moved to any shared filesystem, such as a flash or cloud drive, and it could be installed or extracted in the same manner as is the official release.
```
cp ~/src/phoenix-firestorm/build-linux-x86_64/newview/Phoenix*.tar.* /path/to/shared/drive
```
or
```
mv ~/src/phoenix-firestorm/build-linux-x86_64/newview/Phoenix*.tar.* /path/to/shared/drive
```
When copying the ready-to-run folders and files, use
```
rsync -rptgoDLK --update --progress ~/src/phoenix-firestorm/build-linux-x86_64/newview/packaged/* /path/to/destination
```
Using rsync has the advantage of updating the destination, replacing only those files that changed or are missing, which takes much less time than copying and replacing every file.
## Running your newly built viewer
### Running from a menu item
Create the desktop launcher after copying to the destination machine
```
cd /path/to/firestorm
etc/refresh_desktop_app_entry.sh
```
Then open your applications menu and look in the Internet or Network branch for the Firestorm launcher.
### Running from command line or file browser
```
cd /path/to/firestorm
./firestorm
```
## Troubleshooting
### Handling problems
If you encounter errors or run into problems, please first double check that you followed the steps correctly. One typo can break it. Then, check whether someone else already had the same issue. A solution might be known already.
- **Firestorm Self-Compilers group:** [Firestorm Self Compilers](https://tinyurl.com/firestorm-self-compilers) is free to join, fellow self-compilers may be able to offer assistance.
- **Jira:** [JIRA](https://jira.firestormviewer.org) may contain resolved issues related to the error you're seeing. Search using the error you encountered. Or create a new issue to report an error in this document, or if a code change causes a build process to fail.
### Common issues/bugs/glitches and solutions
- **Virtual memory exhausted, c++ fatal error, or similar out-of-memory issues** may occur if you are building the viewer for the first time, or re-building after a very large set of changes were added. Sometimes restarting the build command will let you recover, sometimes you have to restart the build system. To avoid that from happening, add ram to your virtual environment, or add swap space, something on the order of 10GB or more. As well, reducing the number of CPU cores assigned, down to 4 or less, will lower ram usage.
- **Missing libraries/applications/packages:** This may occur if you did not or could not install the packages shown above, or are attempting to use this procedure with a different Linux OS, or are attempting to build a 32-bit viewer. Start over, making sure you are using the right OS, reinstall all packages as listed, and do not attempt to make a 32-bit viewer.
- **SDL2:** Currently the SDL2 install/update process has a problem if the SDL2 files already exist. The workaround is to delete those files:
```
rm -rf ../build-linux-x86_64/packages/include/SDL2/
rm -rf ../build-linux-x86_64/packages/docs/SDL/
rm ../build-linux-x86_64/packages/LICENSES/SDL.txt
rm ../build-linux-x86_64/packages/lib/release/*SDL*
```
- **Delayed sounds:** Some users have noted that OpenAL plays sounds from the viewer up to 20 seconds after they are triggered. There is no solution to this via the viewer, but there may be some solutions on the Internet. Compiling with FModStudio may resolve this issue.
- **No sounds:** The viewer will try to use whatever sound service you have running, but might need a little coaxing. Read through the firestorm script inside the program directlry, you will find various commented options. Uncommenting one or more may help restore sound, as can compiling with FModStudio. Refer also to the README.Linux.txt and README-linux-voice.txt files in the program directory.
- **Voice won't connect:** Refer to **[this link](https://wiki.firestormviewer.org/fs_voice#linux)** or the relevant link on **[this page](https://wiki.firestormviewer.org/linux)** to make needed adjustments to your computer and/or the SLVoice files.
doc/building_macos.md
+249
View File
@@ -0,0 +1,249 @@
# Build instructions for macOS
The viewer and its libraries are built with the current version of Xcode and Cmake, as well as the standard version of Autobuild from Linden Lab.
> [!WARNING]
> Please note that we do not give support for compiling the viewer on your own. However, there is a self-compilers group in Second Life that can be joined to ask questions related to compiling the viewer: [Firestorm Self Compilers](https://tinyurl.com/firestorm-self-compilers)
## Obtaining a shell to work with
The steps listed below are expected to be run from a shell prompt. Simply copy and paste the commands, or type them out if you wish, into a shell prompt when told to. If you do not know how to acquire a shell prompt, open up the Applications folder, go to Utilities, then open Terminal. This will open a shell prompt. If you are a power user and know what a shell prompt is, open one now using your preferred method and program, then continue on to the next section. Leave this window open throughout the guide. You don't need to close it and re-open it after every command.
## Getting development tools
You will need to install the following tools:
### Xcode
- Xcode, It's a free download from Apple, but the latest version (12.x) is too new, so you will need to get an older version.
- To download a version that will work (11.7 in this case), go [here](https://developer.apple.com/download) and log in with an apple ID.
- Either find the 11.7 download in the list or use this [direct link](https://download.developer.apple.com/Developer_Tools/Xcode_11.7/Xcode_11.7.xip) (will prompt you to log in if you skipped the above step.)
- Open the downloaded file and copy the Xcode application to the Applications folder.
- Open Xcode at least once to set up everything to compile the viewer later on.
- Test by running `clang --version` from the terminal window.
- It should report version 11 something (Apple clang version 11.0.3 (clang-1103.0.32.62) for example.)
- If it reports version 12, something is messed up and you installed Xcode 12.
### CMake
- Download [CMake](http://www.cmake.org/download) version 3.16.0 or higher
- Open the downloaded file and copy CMake to the Applications folder.
- You will need to install the command line links manually. To do this, run from the terminal: `sudo /Applications/CMake.app/Contents/MacOS/CMake --install`
- Again, test by running: `cmake --version` from the terminal window.
### Pip
The pip Python package installation tool is required for the next step. To install it, run from terminal:
```
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo python3 get-pip.py
```
### Autobuild
The Linden Lab [Autobuild](https://github.com/secondlife/autobuild) tool.
- Use the following command to install it on your machine:
```
pip3 install --user -r requirements.txt
```
- Add it to your PATH environment variable so it can be found by the shell. The macOS-approved way to do this is to issue the following command (This change will not take effect until the next time you open a Terminal window.):
```
echo '~/Library/Python/3.7/bin/' | sudo tee /etc/paths.d/99-autobuild
```
- If you do not want to close and re-open your terminal, type the following to add it your PATH (otherwise if you did close it down, re-open it as shown above [here](#obtaining-a-shell-to-work-with)):
```
export PATH=$PATH:~/Library/Python/3.7/bin/
```
- Check Autobuild version to be "autobuild 3.9.3" or higher: `autobuild --version`
### Additional third party libraries
If you want to use licensed FMOD Studio API or KDU build libraries (they are optional) you have to provide these yourself. If you're building Firestorm as part of the project team, ask for the libraries for fmodstudio and kdu. Put them into `/opt/firestorm`.
If you're a community builder, you'll need to build these libraries yourself, then change your autobuild.xml file to point to your own versions, or create a different autobuild.xml with your customizations, and use this with autobuild instead of our default autobuild.xml. There are some examples of how to build FMOD Studio on the LL Wiki and opensource-dev mailing list.
We've created a non-KDU build target to make this easier. Everywhere you see "ReleaseFS" below, use "ReleaseFS_open" instead. This will perform the same build, using openjpeg instead of KDU and omitting FMOD Studio.
Available premade firestorm-specific build targets:
```
ReleaseFS (includes KDU, FMOD)
ReleaseFS_open (no KDU, no FMOD)
RelWithDebInfo_open (no KDU, no FMOD)
```
To build firestorm:
```
autobuild build -c ReleaseFS
```
Other examples:
```
autobuild configure -c ReleaseFS # basic configuration step, don't build, just configure
autobuild configure -c ReleaseFS -- --clean # clean the output area first, then configure
autobuild configure -c ReleaseFS -- --chan Private-Yourname # configure with a custom channel
autobuild build -c ReleaseFS --no-configure # default quick rebuild
autobuild build -c ReleaseFS --no-configure -- --clean # Clean rebuild
autobuild configure -c ReleaseFS_open -- # configure with no third-party libraries
autobuild configure -c ReleaseFS_open -- --fmodstudio # configure with FMOD Studio but no KDU
```
Any of the configure options can also be used (and do the same thing) with the build options. Typical LL autobuild configure options should also work, as long as they don't duplicate configuration we are already doing.
Logs: Look for logs in `build-darwin-x86_64/logs`.
Output: Look for output in `build-darwin-x86_64/newview/Release`.
## Set up your source code tree
Plan your directory structure ahead of time. If you are going to be producing changes or patches you will be cloning a copy of an unaltered source code tree for every change or patch you make, so you might want to have all this work stored in its own directory. If you are a casual compiler and won't be producing any changes, you can use one directory. For this document, we will assume $HOME/firestorm.
```
mkdir ~/firestorm
cd ~/firestorm
git clone https://github.com/FirestormViewer/phoenix-firestorm.git
```
This can take a while. It's a rather large download.
You will also need to download the build variables used for building the viewer. Like the viewer source, these are downloaded from the Firestorm git repository. Assuming you are still in your ~/firestorm directory (or wherever else you chose), issue the following commands:
```
git clone https://github.com/FirestormViewer/fs-build-variables.git
```
You will then need to add this line to your ~/.zshrc file (assuming you are on Catalina or later):
```
echo 'AUTOBUILD_VARIABLES_FILE=~/firestorm/fs-build-variables/variables' | sudo tee ~/.zshrc
```
Again, if you do not wish to restart your terminal:
```
export AUTOBUILD_VARIABLES_FILE=~/firestorm/fs-build-variables/variables
```
## Prepare third party libraries
Most third party libraries needed to build the viewer will be automatically downloaded for you and installed into the build directory within your source tree during compilation. Some need to be manually prepared and are not normally required when using an open source configuration (ReleaseFS_open).
### FMOD Studio using autobuild
- Get the FMOD Studio API disk image installer for the Mac from the [FMOD site](https://www.fmod.com) (requires creating an account to access the download section).
> [!IMPORTANT]
> Make sure to download the FMOD Studio API and not the FMOD Studio Tool!
- Enter these commands into the terminal window:
```
git clone https://github.com/FirestormViewer/3p-fmodstudio.git
cd 3p-fmodstudio
```
- Place the installer disk image (.dmg) file you downloaded into the current directory.
- Issue the following commands:
```
autobuild build
autobuild package --results-file result.txt
```
Near the top of the output you will see the package name written:
```
wrote /Users/yourname/3p-fmodstudio/fmodstudio-2.01.05-darwin-202981448.tar.bz2
```
Additionally, a file `result.txt` has been created containing the md5 hash value of the package file, which you will need in the next step.
- Next, update Firestorms autobuild.xml file to use your FMOD Studio.
```
cd ~/firestorm/phoenix-firestorm
cp autobuild.xml my_autobuild.xml
export AUTOBUILD_CONFIG_FILE=my_autobuild.xml
```
- Copy the fmodstudio path and md5 value from the package process into this command:
```
autobuild installables edit fmodstudio platform=darwin64 hash=<md5 value> url=file:///<fmod path>
```
For example:
```
autobuild installables edit fmodstudio platform=darwin64 hash=3b0d38f2a17ff1b73c8ab6dffbd661eb url=file:///Users/yourname/3p-fmodstudio/https://fmodstudio-2.01.05-darwin-202981448.tar.bz2
```
> [!NOTE]
> Having to copy autobuild.xml and modify the copy from within a cloned repository is a lot of work for every repository you make, but this is the only way to guarantee you pick up upstream changes to autobuild.xml and do not send up a modified autobuild.xml when you do a git push.
## Configuring the Viewer
The following is all still done from within the terminal window:
```
cd ~/firestorm/phoenix-firestorm
autobuild configure -A 64 -c ReleaseFS_open
```
This will configure the viewer for compiling with all defaults and without third party libraries.
### Configuration Switches
There are a number of switches you can use to modify the configuration process. The name of each switch is followed by its type and then by the value you want to set.
- FMODSTUDIO (bool) controls if the FMOD Studio package is incorporated into the viewer. You must have performed the FMOD Studio installation steps in [FMOD Studio using autobuild](#fmod-studio-using-autobuild) for this to work. This is the switch the --fmodstudio build argument sets.
- LL_TESTS (bool) controls if the tests are compiled and run. There are quite a lot of them so excluding them is recommended unless you have some reason to need one or more of them.
> [!TIP]
> OFF and NO are the same as FALSE; anything else is considered to be TRUE
Example:
```
autobuild configure -A 64 -c ReleaseFS_open -- -DLL_TESTS:BOOL=FALSE -DFMODSTUDIO:BOOL=TRUE
```
```
autobuild configure -A 64 -c ReleaseFS_open
```
> [!IMPORTANT]
> You must specify the -A 64 switch to autobuild whenever you configure or build. This tells autobuild to build a 64-bit viewer; this is the only architecture supported on macOS.
## Compiling the Viewer
To compile the code into an app that can be used on your computer, run the following in the terminal window:
```
cd ~/firestorm/phoenix-firestorm
autobuild build -A 64 -c ReleaseFS_open --no-configure
```
Compiling may take quite a bit of time, depending on how fast your machine is and how much else you're doing.
> [!NOTE]
> It is possible to use autobuild to do both the configure step (only needed once) and the build step with one command (`autobuild build -A 64 -c ReleaseFS[_open] [-- config options]`). Some find it is clearer if these steps are done separately, but can save a bit of time if done together.
## Launching the viewer
Now that the viewer has been compiled, it can be found in `build-darwin-x86_64/newview/Release`. Enter the following into the terminal to open Finder:
```
open build-darwin-x86_64/newview/Release
```
From here you can run it directly or copy it to the Applications folder for ease of finding and running later.
## Updating the viewer
If you want to update your self-compiled viewer, you don't have to go through this entire page again. Follow these steps to pull down any new code and re-compile.
- First you need to change to the directory where you built the viewer before. Assuming you followed the steps above and used the same names, run the following in the terminal window: `cd ~/firestorm/phoenix-firestorm`
- Next, decide if you are going to remove the already compiled files and perform a "Clean build", or if you want to keep the existing build files, "Dirty build". Clean builds are generally recommended by developers but have the downside of building everything again, which comes at a cost of time; dirty builds on the other hand, keep all the previously compiled files and only compile the parts that have changed. The downside to dirty builds comes when a change to a core file is pulled down, which will then cause everything to be rebuilt, negating any speed benefit or possibly taking longer than a clean build.
- If you have picked to do a clean build, run the following in the terminal window, otherwise skip to the next step: `rm -r build-darwin-x86_64`
- If you are using a custom autobuild.xml file, then run the following in the terminal window, otherwise skip this step: `export AUTOBUILD_CONFIG_FILE=my_autobuild.xml`
- Now, to pull down any new code, run the following in the terminal window: `git pull`
- After any new code is downloaded, it needs to be reconfigured. Run the following in the terminal window: `autobuild configure -A 64 -c ReleaseFS_open`
- Finally, re-compile the viewer with the new changes. Again, in the terminal window, run: `autobuild build -A 64 -c ReleaseFS_open --no-configure`
Finally, follow the instructions in [Launching the viewer](#launching-the-viewer) to run your freshly updated viewer.
doc/building_windows.md
+292
View File
@@ -0,0 +1,292 @@
# Build instructions for Windows
This page describes all necessary steps to build the Firestorm viewer for Windows. For building instructions up to (and including) release 6.5.3, see the archived version for [building with Python 2.7](https://wiki.firestormviewer.org/archive:fs_compiling_firestorm_windows_py_27).
> [!WARNING]
> Please note that we do not give support for compiling the viewer on your own. However, there is a self-compilers group in Second Life that can be joined to ask questions related to compiling the viewer: [Firestorm Self Compilers](https://tinyurl.com/firestorm-self-compilers)
> [!IMPORTANT]
> With the [merge of Linden Lab release 6.6.16](https://github.com/FirestormViewer/phoenix-firestorm/commit/b64793e2b0d14e44274335c874660af9f679f7f8) it is **NOT** possible to create 32bit builds anymore! Only 64bit builds are possible going forward!
## Install required development tools
This is needed for compiling any viewer based on the Linden Lab open source code and only needs to be done once.
All installations are done with default settings (unless told explicitly) - if you change that, you're on your own!
### Windows
- Install Windows 10/11 64bit using your own product key
### Microsoft Visual Studio 2022
- Install Visual Studio 2022
- Run the installer as Administrator (right click, "Run as administrator")
- Check "Desktop development with C++" on the "Workloads" tab.
- All other workload options can be unchecked
> [!TIP]
> If you don't own a copy of a commercial edition of Visual Studio 2022 (e.g. Professional), you might consider installing the [Community version](https://visualstudio.microsoft.com/free-developer-offers)
### Tortoise Git
- Download and install [TortoiseGit 2.9.0 or newer](https://tortoisegit.org) (64bit)
- Note: No option available to install as Administrator
- Use default options (path, components etc.) for Tortoise Git itself
- At some point, it will ask you to download and install Git for Windows
- You can install with default options **EXCEPT** when it asks for "Configuring the line endings conversion": You **MUST** select "Checkout as-is, commit as-is" here!
### CMake
- Download and install at least [CMake 3.16.0](http://www.cmake.org/download)
- Note: No option available to install as Administrator
- At the "Install options" screen, select "Add CMake to the system PATH for all users"
- For everything else, use the default options (path, etc.)
- Make sure that the following directory was added to your path:
For the 32bit version:
`C:\Program Files (x86)\CMake\bin`
For the 64bit version:
`C:\Program Files\CMake\bin`
### Cygwin
- Download and install [Cygwin 64](http://cygwin.com/install.html) (64bit)
- Run the installer as Administrator (right click, "Run as administrator")
- Use default options (path, components etc.) *until* you get to the "Select Packages" screen
- Add additional packages:
- Devel/patch
- Use default options for everything else
- Make sure that the following directory was added to your path and that it is placed before "%SystemRoot%\system32":
`C:\Cygwin64\bin`
### Python
- Download and install the most recent version of [Python 3](https://www.python.org/downloads/windows)
- Run the installer as Administrator (right click, “Run as administrator”)
- Tick "Add Python 3.10 to PATH"
- Choose the "Customize Installation" option.
- Make sure that "pip" is ticked.
- "Documentation", "tcl/tk and IDLE", "Python test suite" and "py launcher" are not needed to compile the viewer but can be selected if you wish.
- On the next screen, the correct options should already be ticked.
- Set custom install location to: `C:\Python3`
- Make sure that the following directory was added to your path: `C:\Python3`
> [!TIP]
> On Windows 10/11, you also might want to disable the app alias for Python. Open the Windows settings app, search for "Manage app execution aliases" and disable the alias for "python3.exe"
### Intermediate check
Confirm things are installed properly so far by opening a Cygwin terminal and enter:
```
cmake --version
git --version
python --version
pip --version
```
If they all report sensible values and not "Command not found" errors, then you are in good shape.
> [!NOTE]
> The Cygwin terminal is only needed for testing. All commands for actually building the viewer will be run from the Windows command shell.
### Set up Autobuild
- Install Autobuild
You can install autobuild and its dependencies using the `requirements.txt` file that is part of the repo, this will build using the same versions that our official builds use.
- Open Windows Command Prompt and enter: <code>pip install -r requirements.txt</code>
- Autobuild will be installed. **Earlier versions of Autobuild could be made to work by just putting the source files into your path correctly; this is no longer true - Autobuild _must_ be installed as described here.**
- Open Windows Command Prompt and enter:
`pip install git+https://github.com/secondlife/autobuild.git#egg=autobuild`
- Set environment variable AUTOBUILD_VSVER to 170 (170 = Visual Studio 2022).
- Check Autobuild version to be "autobuild 3.8" or higher:
`autobuild --version`
### NSIS
- If you plan to package the viewer and create an installer file, you must install the NSIS from the [official website](https://nsis.sourceforge.io).
- Not required unless you need to build an actual viewer installer for distribution, or change the NSIS installer package logic itself
> [!IMPORTANT]
> If you want to package the viewer built on a revision prior to the [Bugsplat merge](https://github.com/FirestormViewer/phoenix-firestorm/commit/a399c6778579ac7c8965737088c275dde1371c9e), you must install the Unicode version of NSIS [from here](http://www.scratchpaper.com) - the installer from the NSIS website **WILL NOT** work!
## Setup viewer build variables
In order to make it easier to build collections of related packages (such as the viewer and all the library packages that it imports) with the same compilation options, Autobuild expects a file of variable definitions. This can be set using the environmenat variable AUTOBUILD_VARIABLES_FILE.
- Clone the build variables repository:
`git clone https://github.com/FirestormViewer/fs-build-variables.git <path-to-your-variables-file>`
- Set the environment variable AUTOBUILD_VARIABLES_FILE to
`<path-to-your-variables-file>\variables`
## Configure Visual Studio 2022 (optional)
- Start the IDE
- Navigate to **Tools** > **Options** > **Projects and Solutions** > **Build and Run** and set **maximum number of parallel projects builds** to **1**.
## Set up your source code tree
Plan your directory structure ahead of time. If you are going to be producing changes or patches you will be cloning a copy of an unaltered source code tree for every change or patch you make, so you might want to have all this work stored in its own directory. If you are a casual compiler and won't be producing any changes, you can use one directory. For this document, it is assumed that you created a folder c:\firestorm.
```
c:
cd \firestorm
git clone https://github.com/FirestormViewer/phoenix-firestorm.git
```
## Prepare third party libraries
Most third party libraries needed to build the viewer will be automatically downloaded for you and installed into the build directory within your source tree during compilation. Some need to be manually prepared and are not normally required when using an open source configuration (ReleaseFS_open).
> [!IMPORTANT]
> If you are manually building the third party libraries, you will have to build the correct version (32bit libraries for a 32bit viewer, 64bit versions for a 64bit viewer)!
## FMOD Studio using Autobuild
If you want to use FMOD Studio to play sounds within the viewer, you will have to download your own copy. FMOD Studio can be downloaded [here](https://www.fmod.com) (requires creating an account to access the download section).
> [!IMPORTANT]
> Make sure to download the FMOD Studio API and not the FMOD Studio Tool!
```
c:
cd \firestorm
git clone https://github.com/FirestormViewer/3p-fmodstudio.git
```
- After you have cloned the repository, copy the downloaded FMOD Studio installer file into the root of the repository
- Make sure to modify the file build-cmd.sh in the root of the repository and set the correct version number based on the version you downloaded. Right at the top, you find the version number of FMOD Studio you want to package (one short version without separator and one long version):
```
FMOD_VERSION="20102"
FMOD_VERSION_PRETTY="2.01.02"
```
Continue on the Windows command line:
```
c:
cd \firestorm\3p-fmodstudio
autobuild build -A 64 --all
autobuild package -A 64 --results-file result.txt
```
While running the Autobuild build command, Windows might ask if you want to allow making changes to the computer. This is because of the FMOD Studio installer being executed. Allow these changes to be made.
Near the end of the output you will see the package name written:
```
wrote C:\firestorm\3p-fmodstudio\fmodstudio-{version#}-windows64-{build_id}.tar.bz2''
```
where {version#} is the version of FMOD Studio (like 2.01.02) and {build_id} is an internal build id of the package. Additionally, a file `result.txt` has been created containing the md5 hash value of the package file, which you will need in the next step.
```
cd \firestorm\phoenix-firestorm
cp autobuild.xml my_autobuild.xml
set AUTOBUILD_CONFIG_FILE=my_autobuild.xml
```
Copy the FMOD Studio path and md5 value from the package process into this command:
`autobuild installables edit fmodstudio platform=windows64 hash=<md5 value> url=file:///<fmodstudio path>`
For example:
`autobuild installables edit fmodstudio platform=windows64 hash=a0d1821154e7ce5c418e3cdc2f26f3fc url=file:///C:/firestorm/3p-fmodstudio/fmodstudio-2.01.02-windows-192171947.tar.bz2`
> [!NOTE]
> Having to copy autobuild.xml and modify the copy from within a cloned repository is a lot of work for every repository you make, but this is the only way to guarantee you pick up upstream changes to autobuild.xml and do not send up a modified autobuild.xml when you do a git push.
## Configuring the viewer
Open the Windows command prompt.
If you are building with FMOD Studio and have followed the previous FMOD Studio setup instructions AND you are now using a new terminal you will need to reset the environment variable first by entering
`set AUTOBUILD_CONFIG_FILE=my_autobuild.xml`
Then enter:
```
c:
cd \firestorm\phoenix-firestorm
autobuild configure -A 64 -c ReleaseFS_open
```
This will configure Firestorm to be built with all defaults and without third party libraries.
Available premade firestorm-specific build targets:
```
ReleaseFS (includes KDU, FMOD)
ReleaseFS_open (no KDU, no FMOD)
RelWithDebInfoFS_open (no KDU, no FMOD)
```
> [!TIP]
> Configuring the viewer for the first time will take some time to download all the required third-party libraries. The download progress is hidden by default. If you want to watch the download progress, you can use the verbose option to display a more detailed output:
> `autobuild configure -A 64 -v -c ReleaseFS_open`
### Configuration switches
There are a number of switches you can use to modify the configuration process. The name of each switch is followed by its type and then by the value you want to set.
- -A \<architecture\> sets the target architecture, that is if you want to build a 32bit or 64bit viewer (32bit is default if omitted).
- --fmodstudio controls if the FMOD Studio package is incorporated into the viewer. You must have performed the FMOD Studio installation steps in [FMOD Studio using Autobuild](#fmod-studio-using-autobuild) for this to work.
- --package makes sure all files are copied into viewers output directory. You won't be able to start your compiled viewer if you don't enable package or do 'compile' it in VS.
- --chan \<channel name\> lets you define a custom channel name for the viewer
- -LL_TESTS:BOOL=\<bool\> controls if the tests are compiled and run. There are quite a lot of them so excluding them is recommended unless you have some reason to need one or more of them.
> [!TIP]
> **OFF** and **NO** are the same as **FALSE**; anything else is considered to be **TRUE**
Examples:
- To build a 64bit viewer with FMOD Studio and to create an installer package, run this command in the Windows command window:
`autobuild configure -A 64 -c ReleaseFS_open -- --fmodstudio --package --chan MyViewer -DLL_TESTS:BOOL=FALSE`
- To build a 64bit viewer without FMOD Studio and without installer package, run this command:
`autobuild configure -A 64 -c ReleaseFS_open -- --chan MyViewer -DLL_TESTS:BOOL=FALSE`
## Building the viewer
There are two ways to build the viewer: Via Windows command line or from within Visual Studio.
### Building from the Windows command line
If you are building with FMOD Studio and have followed the previous FMOD Studio setup instructions AND you are now using a new terminal you will need to reset the environment variable with
`set AUTOBUILD_CONFIG_FILE=my_autobuild.xml`
Then run the Autobuild build command. Make sure you include the same architecture parameter you used while [configuring the viewer](#configuring-the-viewer):
`autobuild build -A 64 -c ReleaseFS_open --no-configure`
Compiling will take quite a bit of time.
### Building from within Visual Studio
Inside the Firestorm source folder, you will find a folder named build-vc170-\<architecture\>, with \<architecture\> either being 32 or 64, depending on what you chose during the configuration step. Inside the folder is the Visual Studio solution file for Firestorm, called Firestorm.sln.
- Double-click Firestorm.sln to open the Firestorm solution in Visual Studio.
- From the menu, choose Build -> Build Solution
- Wait until the build is finished
## Troubleshooting
### SystemRootsystem32: unbound variable
When trying to execute the Autobuild build command, you might encounter an error similar to
`../build.cmd.sh line 200: SystemRootsystem32: unbound variable`
This error is caused by the order of the items in the Windows "path" environment variable. Autobuild exports all paths set in the "path" environment variable into Cygpath names and variables. Since these Windows "paths" can also contain variables like %SystemRoot% and they can also depend on each other, it is important to keep the dependency order intact. Example:
```
%SystemRoot%
%SystemRoot%\system32
%SystemRoot%\System32\Wbem
```
Make sure the ones mentioned are the first items set in the "path" environment variable.
doc/contributions.txt
Executable
+1738
View File
File diff suppressed because it is too large Load Diff
doc/firestorm_256.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 143 KiB

doc/testplans/RenderMaxTextureResolution.md
+16
View File
@@ -0,0 +1,16 @@
The Setting RenderMaxTextureResolution controls the maximum resolution of non-boosted textures as displayed by the viewer.
Valid values are 512-2048 (clamped in C++).
![image](https://github.com/secondlife/viewer/assets/23218274/d0f889fc-8135-41d2-9d83-871ad4eebed5)
![image](https://github.com/secondlife/viewer/assets/23218274/19950828-7eb1-4bb2-85d7-f35c63b34294)
![image](https://github.com/secondlife/viewer/assets/23218274/249afc83-4de6-488d-a05e-4877d08573b1)
Test Asset available on beta grid:
Object: 'Damaged Helmet', AssetID 0623e759-11b5-746c-a75e-7ba1caa6eb0e
doc/testplans/hdri_local_preview.md
+21
View File
@@ -0,0 +1,21 @@
A resident may swap out their sky for an EXR format HDRI for the purposes of previewing how their object would render in Second Life in an environment that matches the supplied HDRI. This should aid in matching inworld lighting with external tools so artists can know if their content has imported properly.
To load an HDRI, click Develop->Render Tests->HDRI Preview:
![image](https://github.com/secondlife/viewer/assets/23218274/fbdeab5f-dc1f-4406-be19-0c9ee7437b3f)
Choose an EXR image. A library of publicly available HDRIs can be found here: https://polyhaven.com/hdris
The Personal Lighting floater will open, and the sky will be replaced with the HDRI you chose. Reflection Probes will reset, and the scene will be illuminated by the HDRI.
Three debug settings affect how the HDRI is displayed:
RenderHDRIExposure - Exposure adjustment of HDRI when previewing an HDRI. Units are EV. Sane values would be -10 to 10.
RenderHDRIRotation - Rotation (in degrees) of environment when previewing an HDRI.
RenderHDRISplitScreen - What percentage of screen to render using HDRI vs EEP sky.
Exposure and Rotation should behave similarly to the rotation and exposure controls in Substance Painter.
Split Screen can be used to display an EEP sky side-by-side with an HDRI sky to aid in authoring an EEP sky that matches an HDRI sky. It is currently expected that EEP sun disc, moon, clouds, and stars do not render when previewing an HDRI, but that may change in the future.
doc/testplans/material_preview.md
+83
View File
@@ -0,0 +1,83 @@
# Material Preview
## Overview
Material preview is a UI feature which displays a lit spherical preview of a PBR material. It can be found in the following UIs:
- The material picker swatch
- In the build floater, in the Texture tab, when applying a PBR material
- (If the feature is enabled) In the Region/Estate floater, in the Terrain tab, when applying PBR materials to terrain
- In the floater to select a material from inventory, which can be opened by clicking the material picker swatch
## Known Issues
These are known issues that the current implementation of this feature does not address:
- The material preview in the build floater is a preview of the base material ID only, and ignores other properties on the prim face like material overrides (https://github.com/secondlife/viewer/issues/865)
- Alpha mask previews as alpha blend (https://github.com/secondlife/viewer/issues/866)
- Double-sided previews as single-sided (https://github.com/secondlife/viewer/issues/867)
- Material preview inherits some of its lighting from the current environment, and reflections from the default reflection probe (https://github.com/secondlife/viewer/issues/868)
## General Regression Testing
- Check that the material preview swatch looks OK with different materials selected
- Check that the material preview swatch runs reasonably well on different systems, especially when the select material from inventory floater is also open
- In particular: AMD, MacOS, minimum spec machines
- Watch out for regressions in rendering caused by opening a floater with a material preview swatch
## Bug Fixes
### Disappearing Objects Fix Test
This test is recommended for verifying that https://github.com/secondlife/viewer-issues/issues/72 is fixed.
#### Symptoms
When the bug occurs, one or more of following types of objects could randomly disappear in the world, permanently until relog:
- Objects
- Water level in current region
- Adjacent region/void water
Note: Disappearing objects in reflections have a different root cause and are not covered by the fix.
#### Bug Reproduction Steps
Verify the disappearing objects bug does not reproduce, given the following steps:
- Runtime prerequisites: Material preview swatch may not be available in your viewer or region if this feature is still behind a feature flag. It is safe to enable this feature manually by setting, "UIPreviewMaterial" to True in the advanced settings. The setting will persist for the current session.
- Region prerequisites: Unknown, but a region with lots of objects in it seems to increase repro rate. The following locations have been known to easily reproduce the bug, as of 2024-02-16:
- http://maps.secondlife.com/secondlife/LindenWorld%20B/161/75/47
- [secondlife://Aditi/secondlife/Rumpus%20Room%202048/128/128/24](secondlife://Aditi/secondlife/Rumpus%20Room%202048/128/128/24)
- Right click an object and select, "Edit item"
- Go to texture tab, select PBR Metallic Roughness from dropdown, and click the button to select material from inventory
- Ensure "Apply now" is checked in the inventory selection floater
- Alternate between different materials from the inventory selection floater
- Look around the world and check for permanently disappeared objects.
### Dynamic Exposure Influence Fix Test
This test is recommended for verifying that https://github.com/secondlife/viewer-issues/issues/72 is fixed.
#### Symptoms
Dynamic exposure in the world could be influenced by the material preview being displayed. If a material preview was being generated in a given frame, then, depending on the current environment, the user would observe an unpleasant flashing effect in the environment:
- The world view could suddenly get darker and then fade back to normal exposure levels
- The world view could suddenly get brighter and then fade back to normal exposure levels
#### Bug Reproduction Steps
Verify the dynamic exposure influence bug does not reproduce. Test using a few environment presets such as Default Midday, Sunset, and Midnight.
- Right click an object and select, "Edit item"
- Go to texture tab, select PBR Metallic Roughness from dropdown, and click the button to select material from inventory
- Alternate between different materials from the inventory selection floater
#### Regression Testing
Dynamic exposure in the world should continue to work correctly. In particular:
- Exposure should fade gradually from high exposure to low exposure and back as needed
- Exposure should decrease in brighter environments
- Exposure should increase in darker environments
doc/testplans/optimize_away_alpha.md
+5
View File
@@ -0,0 +1,5 @@
Textures imported via Build->Upload->Material that have an all opaque (255) alpha channel should have their alpha channel removed before upload.
1. Make 4 images that have different colors but all 255 alpha channels
2. Upload them all using Build->Upload->Material, with one in each of the material texture slots
3. Verify that using the textures as a blinn-phong diffuse map does not make the corresponding face render in the alpha pass (face should stay visible after disabling alpha pass by unchecking Advanced->Render Types->Alpha).
doc/testplans/pbr_materials.md
+12
View File
@@ -0,0 +1,12 @@
# PBR Materials
## KHR Texture Transforms
Texture repeats for PBR materials on prims are based on the [KHR\_texture\_transform](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_transform) spec, and thus should be expected to behave according to the spec. We currently suport offset, rotation, and scale from the spec. texCoord is not currently supported.
PBR materials should have approximately correct lighting based on the normal texture:
- With default texture transforms, assuming the prim or model has correct normals and tangents
- With a texture transform applied, especially rotation or negative scale
- With a texture animation applied via `llSetTextureAnim`, especially a rotation animation
- Note: Texture animations are not guaranteed to loop when a PBR texture transform is applied
doc/testplans/pbr_terrain_appearance.md
+63
View File
@@ -0,0 +1,63 @@
# PBR Terrain Appearance
## Tiling Without Texture Transforms
This section assumes the PBR terrain of the current region and adjacent regions have the default texture transforms.
The southwest corner of a region with PBR materials should exactly match up with the bottom left corner of the material texture(s).
If two adjacent regions have the same PBR terrain settings, then there should not be seams between the two regions at their shared border.
The ground should not suddenly slide beneath the avatar when moving between two PBR terrain regions (except due to movement of the avatar, which is not covered by this test plan)
## Feature Gating
PBR terrain should have lower detail on lower graphics settings. PBR terrain will also not show emissive textures on some machines (like Macs) which do not support more than 16 textures.
### Triplanar Mapping
Triplanar mapping improves the texture repeats on the sides of terrain slopes.
Availability of Triplanar mapping:
- Medium-High and below: No triplanar mapping
- High and above: Triplanar mapping
### PBR Textures
At the highest graphics support level, PBR terrain supports all PBR textures.
Availability of PBR textures varies by machine and graphics setting:
- Low: Base color only (looks similar to texture terrain)
- Medium-Low, and machines that do not support greater than 16 textures such as Macs: All PBR textures enabled except emissive textures.
- Medium: All PBR textures enabled
### PBR Alpha
PBR terrain does not support materials with alpha blend or double-sided. In addition, the viewer does not make any guarantees about what will render behind the terrain if alpha is used.
## PBR Terrain Texture Transforms
Like PBR materials on prims, PBR terrain repeats are based on the [KHR\_texture\_transform](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_transform) spec, and thus should be expected to behave the same way. We currently suport offset, rotation, and scale from the spec. texCoord is not currently supported.
The southwest corner of a region, at z=0, is the UV origin for all texture coordinates of the whole region. Unless an offset is also applied, scale and rotation of the terrain texture transforms are relative to that point.
When an avatar faces north and looks down at flat ground, the textures of the materials should appear to face upright, unless a rotation is applied.
If triplanar mapping is enabled, and an avatar faces an axially-aligned wall, the textures of the materials should appear to face upright, unless a rotation is applied.
Textures of materials should not appear mirrored.
When triplanar mapping is enabled, rotations on the axially aligned walls should apply in the same direction as they would on flat ground.
## PBR Terrain Normal Textures
This section assumes terrain normal maps are enabled at the current graphics setting.
PBR terrain should have approximately correct lighting based on the normal texture:
- When on flat ground
- On cliffs, when triplanar mapping is enabled. Lighting will be somewhat less accurate when the cliff face is not axially aligned.
- If no Terrain Texture Transform is applied.
- If a Terrain Texture Transform is applied, especially for rotation or negative scale.
doc/testplans/pbr_terrain_composition.md
+106
View File
@@ -0,0 +1,106 @@
# PBR Terrain Composition
## Feature Availability
PBR Terrain is visible for all viewers with the PBR Terrain feature, regardless of if the feature flag is enabled.
There is only one set of four asset IDs applied to the terrain. In other words, unlike PBR materials on prims, there is no fallback texture set for viewers that do not support PBR terrain. Viewers without support will view terrain as blank (solid grey or white).
## Editing Terrain Composition
All tests in this section assume the PBR terrain feature flag is enabled, and that the user has appropriate permissions to modify the terrain textures.
### Feature Availability
These features are related to UI, where the Region/Estate floater is opened to the terrain Tab.
#### Feature: PBR Terrain
On the client, the advanced setting `RenderTerrainPBREnabled` is the PBR terrain feature flag.
The PBR terrain feature flag should be set automatically when logging in/teleporting to a new region.
- The flag should be enabled on regions where the PBR terrain feature is enabled
- Otherwise the flag should be disabled
When the PBR terrain feature flag is disabled:
- The "PBR Metallic Roughness" checkbox should not be visible
- The user should not be able to apply PBR terrain to the region, only textures.
When the PBR terrain feature flag is enabled:
- The "PBR Metallic Roughness" checkbox should be visible
- The user should be able to apply PBR terrain or textures to the region, depending on if the "PBR Metallic Roughness" checkbox is checked.
#### Feature: PBR Terrain Texture Transforms
On the client, the advanced setting, `RenderTerrainPBRTransformsEnabled` is the PBR terrain texture transform flag. Generally, this feature should not be expected to work correctly unless the PBR terrain feature is also enabled.
The PBR terrain texture transform flag should be set automatically when logging in/teleporting to a new region.
- The flag should be enabled on regions where the PBR terrain texture transform feature is enabled
- Otherwise the flag should be disabled
When the PBR terrain texture transform feature is enabled, the UI of the Terrain tab should be overhauled. Availability of features depends on the type of terrain.
**Known issue:** The Region/Estate floater may have to be closed/reopened a second time in order for the UI overhaul to take effect, after teleporting between regions that do and do not have the feature flag set.
When "PBR Metallic Roughness" is checked:
- There should be a way for the user to change the texture transforms for the terrain in the current region
- For each of the four swatches, the user can change the scale, offset, and rotation of that swatch. Nonuniform scale is allowed
When "PBR Metallic Roughness" is unchecked, the controls for texture transforms should be hidden.
### Current Composition Type
When the Region/Estate floater is opened to the terrain Tab, the current terrain should be shown in the four swatches, and the "PBR Metallic Roughness" checkbox should be checked or unchecked accordingly.
- If it is texture terrain, the "PBR Metallic Roughness" checkbox should be unchecked, and the floater should display the four textures applied to the terrain.
- If it is material terrain, the "PBR Metallic Roughness" checkbox should be checked, and the floater should display the four materials applied to the terrain.
In addition, where possible, textual labels and descriptions in the tab should make sense given the current value of the "PBR Metallic Roughness" checkbox. If the checkbox is unchecked, the labels should refer to textures. If the checkbox is checked, the labels should refer to materials.
### Toggling Composition Type
When toggling the "PBR Metallic Roughness" checkbox to the opposite value, which does not correspond to the current terrain type, one of the following sets of four terrain swatches will be displayed:
- The default textures/materials
- For textures, this is the default terrain texture set
- For materials, this is all blank materials, but this is subject to change
- The previously applied texture/material set
- History is available on a best-effort basis only. In particular, the history does not persist on viewer restart.
When toggling back the "PBR Metallic Roughness" checkbox to the original value, assuming nothing else has changed, then the current terrain should be shown in the four swatches again.
### Saving Composition
A user with appropriate permissions can change and save the textures or materials to the terrain. If the "PBR Metallic Roughness" checkbox is checked, the user applies materials, otherwise the user applies textures.
The user should not be allowed to set the texture or material swatches to null.
Saving may fail for the following reasons:
- A terrain or material texture is invalid
- A terrain texture is greater than the max texture upload resolution
If saving the terrain fails for any reason, the terrain should not be updated.
Unlike a viewer without PBR terrain support, the new viewer will no longer treat textures with alpha channels as invalid.
### Saving PBR Terrain Texture Transforms
If "PBR Metallic Roughness" checkbox is checked, a user with saving composition permissions should also be allowed to edit and save PBR texture transforms.
One texture transform may be set for each material swatch. Setting texture transforms for each individual texture on the material is not currently supported.
## Graphics Features
Texture terrain with transparency is not permitted to be applied in the viewer.
See [PBR Terrain Appearance](./pbr_terrain_appearance.md) for supported PBR terrain features.
## Minimap
The minimap should display the terrain with appropriate textures and colors.
doc/testplans/pbr_terrain_paintmap.md
+48
View File
@@ -0,0 +1,48 @@
# PBR Terrain Paintmap
## Introduction/Disclaimer
As of 2024-08-06, PBR terrain painting is **WIP**. Currently, there is only a client-side terrain paintmap, with no way to directly edit it. This document will explain how to informally explore this feature and compare it to the existing heightmap with noise. In the future, a testing document will be added for PBR terrain painting.
## Background
Historically, PBR terrain in a region has several parameters for controlling its composition. These are:
- The four materials
- The elevation of the terrain, which roughly controls the material, with some noise added on top ("heightmap with noise")
- Material Elevation Ranges, which control where the materials start and end
This allows for some coarse control over terrain composition. For example, you can have one corner of the terrain be a sandy beach and the rest of the coastline be rocky. Or you can have the peaks of your mountains be covered with snow. However, artistic control is limited due to the gradient imposed by the material elevation ranges, and the unpredictability of the noise.
A terrain painting option would allow for more control over the terrain composition. The first step to getting that working is the paintmap.
## How to activate the local paintmap
The local paintmap is a good way to assess the quality of the PBR terrain paintmap. By default, the newly created local paintmap inherits its composition (i.e. where the grass and dirt goes) from the existing terrain. This allows for a direct comparison with the terrain heightmap-with-noise shader.
Activating the local paintmap is similar to [applying local PBR terrain via the debug settings](https://wiki.secondlife.com/wiki/PBR_Terrain#How_to_apply_PBR_Terrain), but with a couple extra steps.
You will need:
- Four fullperm PBR material items to copy UUIDs from
- A region with a good variation of elevations which showcase the four composition layers (no special permissions needed)
Open the Debug Settings menu (Advanced > Show Debug Settings) and search for "terrain". The following relevant options are available:
- LocalTerrainAsset1
- LocalTerrainAsset1
- LocalTerrainAsset3
- LocalTerrainAsset4
- LocalTerrainPaintEnabled
- TerrainPaintBitDepth
- TerrainPaintResolution
By setting LocalTerrainAsset1, etc to valid material IDs, you will override the terrain to use those materials.
The next step is to "bake" the terrain into a paintmap (Develop > Terrain > Create Local Paintmap). This will *automatically* set LocalTerrainPaintEnabled to true. **WARNING:** LocalTerrainPaintEnabled will *not* do anything until one of LocalTerrainAsset1, etc is set.
You are now looking at the same terrain, but rendered as a paintmap.
To compare the quality of the paintmap version and the heightmap-with-noise version, toggle LocalTerrainPaintEnabled in Debug Settings.
To change the bit depth and/or resolution of the paintmap, change TerrainPaintBitDepth and TerrainPaintResolution as desired, then "re-bake" the paintmap (Develop > Terrain > Create Local Paintmap).
doc/testplans/terrain_loading.md
+29
View File
@@ -0,0 +1,29 @@
# Terrain Loading
## Behavior overview
- Texture terrain should load if textures are applied to the region, and no PBR Metallic Roughness materials are applied.
- PBR terrain should load if PBR materials are applied to the region, even if the RenderTerrainPBREnabled feature flag is disabled in debug settings. This setting only disables the display of PBR materials in the Region / Estate > Terrain UI.
- Related subsystem: A change to the PBR terrain loading system may affect the texture terrain loading system and vice-versa
- Related subsystem: Minimap should load if terrain loads
- They may not finish loading at the same time
## Implementation details
This section is provided mainly for clarification of how the terrain loading system works.
The simulator sends 4 terrain composition UUIDs to the viewer for the region. The viewer does not know ahead-of-time if the terrain composition uses textures or materials. Therefore, to expedite terrain loading, the viewer makes up to 8 "top-level" asset requests simultaneously:
- Up to 4 texture asset requests, one for each UUID
- Up to 4 material asset requests, one for each UUID
It is therefore expected that half of these asset lookups will fail.
The viewer inspects the load success of these top-level assets to make the binary decision of whether to render all 4 texture assets or all 4 material assets. This determines the choice of composition for terrain both in-world and on the minimap.
The minimap also attempts to wait for textures to partially load before it can render a tile for a given region:
- When rendering texture terrain, the minimap attempts to wait for top-level texture assets to partially load
- When rendering PBR material terrain, the minimap attempts to wait for any base color/emissive textures in the materials to partially load, if they are present
We don't make guarantees that the minimap tile will render for the region if any aforementioned required textures/materials fail to sufficiently load. However, the minimap may make a best-effort attempt to render the region by ignoring or replacing data.
doc/translations.txt
Executable
+29
View File
@@ -0,0 +1,29 @@
#List of translators who contribute to SL Viewer 2.0+ by language
Danish
Flemming Congrejo
German
Torben Trautman
French
Valerie Linden
Polish
Identity Euler
Portuguese
Zaza Linden
Spanish
Aralara Rajal
Aura Dirval
Cayu Cluny
Eva Rau
FreeSL Aeon
Frontera Thor
Inma Rau
Irene Muni
Lunita Savira
Minerva Memel
Polo Gufler
Xiki Luik
Shinya Tandino
Catwise Yoshikawa
Traditional Chinese
gefeit Dufaux