View source for Project Sunshine-Server Side Appearance

= Server Side "Texture Baking" Viewer Release  =

== Structure of Server side texture baking<br>  ==

[[Image:Server Side Appearance Architecture.png|720px]] 

== Viewer Architecture changes <br>  ==

In order to accomodate the back-end server code we have refactored a significant portion of the avatar appearance pipeline. There is now a new "project" in the indra directory called "llappearance" which defines a set of interface and functional classes that are shared between the viewer and the back end rendering system. These classes were pulled out of newview, and range from avatar definitions (LLVOAvatar), to tex layers and visual parameters. In addition, a number of texture functions and classes have been moved from newview to llrender. In some cases, these classes were subclassed to contain the viewer-specific functionality back in newview. 

Since some of the functionality of the classes was moved to a different directory while other pieces stayed, many merge tools will get confused and not necessarily move your changes to the correct place and in some cases may believe that the proper solution is to remove your fixes or be unable to merge the patches at all. Expect that there will be some manual merging necessary, especially if your viewer has made avatar/appearance changes or tweaks. We will assist whenever possible with questions about the new architecture or merge questions, but the new changes will be necessary for viewers to have after we start to roll out new servers. 

<br> 

== New Network Protocols <br> ==

To support the new featureset, a few of the network protocols have been modified or added to: 

#login now returns a texture fetch url for any baked texture requests<br> 
#Agent Appearance message now contains an extra visual parameter to indicate that it is a new-style message
#Agent Appearance message has an extra (optional) block to indicate appearance version number and current outfit folder version number
#Regions now have a new capability to request an appearance message which will return or regenerate the agent appearance message
#Regions now accept a flag on the reply of a RegionHandshake message that will allow the simulator to identify SSA-capable viewers.

== Forwards and Backwards Compatibility <br>  ==

This project was designed under the assumption that viewers will be updated before the server code gains widespread adoption. However, the server code will take a while to test, scale up, and roll out. As such, the viewer code provided can work fine on the grid as it stands today. The new code should still upload new baked textures and use the old protocols on the main grid. Once a new viewer connects to a new server, that user's appearance message will be converted to a server-generated message that will persist even once you return to an old region. New-style appearance messages will remain flagged as such even when sent by an old region. Since textures are fetched from a central service, updated viewers will be able to fetch an avatar's textures even if the server your agent is on does not support it. 

If you force a rebake or change your outfit while standing on an old-style region, however, your viewer will revert to uploading its own bakes. These will be overwritten when you return to a new-style region. 

Our testing regions on Aditi are set up next to some server-trunk regions so that you can test these transitions. Please be certain to test with multiple viewers so that you can verify that avatar appearance is consistent from multiple users. 

Testing has shown that there is a danger of asset corruption if AvatarAppearance messages for your own avatar are sent to viewer 1.x clients (Phoenix specifically). To combat this, the new simulator will not send such messages for yourself until your viewer can be verified as compatible. As soon as a new region receives an updated RegionHandshakeReply message, or an appearance request from your viewer, it will be marked as compatible. This compatibility flag will follow you as long as you stay on a SSA-enabled region.

== Status of viewer repository<br>  ==

The initial version of the SSA viewer has been released with viewer version 3.5.1. Additionally, the RegionHandshakeReply patch has been released separately here: [https://bitbucket.org/nyx/sunshine-flags/commits/5fdc790f6d8b52e01a6f55ab0a94590b27ecbb06 RegionHandshakeReply patch] . A second round of changes has been started in the sunshine-external repository, but changes located here are not considered of release quality yet. Additional work is required, along with extensive testing. Most Third Party Viewers have integrated the first round of changes, and have been testing its functionality against test regions on Aditi and Agni.
<br> 

Known issues include:
# Agni test regions do not yet protect against SUN-74, the asset corruption bug on Phoenix viewers. This will be fixed with the next server rollout.
# Avatar hover works differently than previous third-party implementations. Hover/offset is adjusted via a wearable parameter update, and must be saved to take effect, making it useful for outfits that need to always be adjusted. This does not cover every use-case for the current third party implementation.
# A handful of difficult to reproduce cases of avatars failing to load exist that are fixed by forcing a rebake or relogging. These appear to be mostly inventory-related and should be improved in later releases.

<br>

Overall the system appears to be nearing readiness for an initial release. Any users that notice bad behavior on test regions/viewers should report them as soon as possible, so any impact on release schedules can be evaluated.

<br> 

Keep checking in for additional information on known issues and updates. More code will be pushed periodically as we fix the remaining issues and make any refinements. 

Note that once this starts to roll out, users who do not update their viewer will not resolve properly to other people. They will see avatars using the new system as grey. See this blog post for details: [http://community.secondlife.com/t5/Featured-News/Faster-Avatar-Loading-on-the-Horizon/ba-p/2026857 Faster Avatar Loading on the Horizon]
<br> 

== Reporting Bugs, assistance with merge issues  ==

The viewer should work as it does today on the main grid. There are regions on Aditi that have the new code ( SunshineTest, SunshineTest1 ). 

Bugs and edge cases with the current state of code, whether in the viewer code or the back-end service should be filed in JIRA under project sunshine ([https://jira.secondlife.com/browse/SUN SUN]).  If you are a developer and cannot access this project, contact [[User:Oz_Linden]].

If you are having trouble with the new re-architecture or merging your appearance changes into the new codebase, please reach out to Nyx Linden (nyx at lindenlab.com). 

<br> 

== Source code & build links<br>  ==
{{ViewerInstallers|{{JiraIssue|SUN|Server Side Texture Baking}}| Support server side texture baking. |task=sunshine-external|repo=https://bitbucket.org/lindenlab/sunshine-external}}