Add support for animated layer effects and a keyframe-based timeline (#1417)

* Start working on animatable layer effects

* Interpolate colors & animated effects work on apply

* Add nodes to change tween properties

* Use smaller texts for the tween property option buttons

* Fix crash when enabling animation, disabling and enabling it again

* Remove keyframes

* Load and save animated parameters in pxo files

* Format

* Start working on a keyframe based timeline

* Create keyframes in the UI

* Start working on keyframe value changing

* Remove animated layer effect code from the layer FX settings

* Refactor animated_params dictionary

* Probably fix pxo loading

At least old pxo files seem to be working properly

* Update timeline when adding/removing keyframes

* Use a tree for the layer elements

Need to implement folding logic for the keyframes themselves though

* Add a timeline cursor

* Improve cursor moving logic

* More timeline cursor improvements

* Some UI improvements

* Make timeline a bit prettier

* Fix animated params pxo loading

* Some small improvements

* Fix scrolling

* Don't create keyframe if there already is one

* Fix frame container not resizing when clicking on keyframes

* Added Constant transition

* Add undo/redo when adding and deleting keyframes

* Fix keyframe unselection

* Start working on multiple selected keyframes

* Change name of a script

* Change properties of all selected keyframes

With undo/redo support

* [WIP] Move keyframes

While it technically works, the UI side is not being updated. Also, I just realized that the way we're handling keyframe creation and deletion is wrong, because the nodes get freed when switching to a different layer, or a different project. So we most likely should just re-create the keyframe nodes when we add, delete or move them. Which means I also need to change the selected_keyframes array to store param_name and frame_index, instead of nodes.

* Add IDs to keyframes for easier handling

* Don't allow keyframes to go below frame 0

Mostly so they can't be lost. The proper solution would be to support negative frames, like Godot's animation player editor does, but this should work for now.

* Zoom in the timeline

* Support booleans and colors, scroll timeline when changing cel or layer

* Implement the keyframe timeline inside the main timeline panel

I feel like the UI does need some improvements still

* Make properties grid container and delete keyframe button persistent nodes

* Undo/redo refreshes the keyframe property UI

* Hide tags when keyframe timeline is visible

* Fix property nodes not having the correct name

* Use a custom node to draw frames instead of using labels

* Fix group layers passthrough mode not having its effect be animated

* Don't create tracks for properties that currently cannot be animated

Such as textures

* Better documentation and future-proofing

Author: OverloadedOrama

assets/graphics/timeline/keyframe.svg

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://yhha3l44svgs"
+path="res://.godot/imported/keyframe.svg-35dec774d84fcacd926a7d0e2d227dd7.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/graphics/timeline/keyframe.svg"
+dest_files=["res://.godot/imported/keyframe.svg-35dec774d84fcacd926a7d0e2d227dd7.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1
+svg/scale=1.0
+editor/scale_with_editor_scale=false
+editor/convert_colors_with_editor_theme=false

assets/graphics/timeline/keyframe.svg.import

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://dtx6hygsgoifb"
+path="res://.godot/imported/keyframe_selected.svg-2f24f41724ac5cd07c9e855421d962fe.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/graphics/timeline/keyframe_selected.svg"
+dest_files=["res://.godot/imported/keyframe_selected.svg-2f24f41724ac5cd07c9e855421d962fe.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1
+svg/scale=1.0
+editor/scale_with_editor_scale=false
+editor/convert_colors_with_editor_theme=false

assets/graphics/timeline/keyframe_selected.svg

@@ -1,14 +1,39 @@
 class_name LayerEffect
 extends RefCounted
 
+signal keyframe_set
+
 var name := ""
 var shader: Shader
+var layer: BaseLayer
 var category := ""
-var params := {}
+var params: Dictionary[String, Variant] = {}
+## A Dictionary containing another Dictionary that
+## maps the frame indices (int) to another Dictionary of value, trans, ease,
+## and a layer-scope unique ID.
+## Example:
+## [codeblock]
+##{
+##	"offset":
+##	{
+##		0: {id: 0, "value": Vector2(0, 0), "trans": 0, "ease": 2},
+##		10: {id: 1, "value": Vector2(64, 64), "trans": 1, "ease": 3},
+##	},
+##	"wrap_around":
+##	{
+##		1: {id: 2, "value": false, "trans": 0, "ease": 0},
+##		3: {id: 3, "value": true, "trans": 0, "ease": 0},
+##		10: {id: 4, "value": false, "trans": 0, "ease": 0},
+##	},
+##}
+## [/codeblock]
+var animated_params: Dictionary[String, Dictionary] = {}
 var enabled := true
 
 
-func _init(_name := "", _shader: Shader = null, _category := "", _params := {}) -> void:
+func _init(
+	_name := "", _shader: Shader = null, _category := "", _params: Dictionary[String, Variant] = {}
+) -> void:
 	name = _name
 	shader = _shader
 	category = _category
@@ -19,11 +44,92 @@ func duplicate() -> LayerEffect:
 	return LayerEffect.new(name, shader, category, params.duplicate())
 
 
+func get_params(frame_index: int) -> Dictionary:
+	var to_return := params.duplicate()
+	for param in animated_params:
+		if param.begins_with("PXO_"):
+			continue
+		var animated_properties := animated_params[param]  # Dictionary[int, Dictionary]
+		if animated_properties.has(frame_index):
+			# If the frame index exists in the properties, get that.
+			to_return[param] = animated_properties[frame_index].get("value", to_return[param])
+		else:
+			if animated_properties.size() == 0:
+				continue
+			# If it doesn't exist, interpolate.
+			var frame_edges := find_frame_edges(frame_index, animated_properties)
+			var min_params: Dictionary = animated_properties[frame_edges[0]]
+			var max_params: Dictionary = animated_properties[frame_edges[1]]
+			var min_value = min_params.get("value", to_return[param])
+			var max_value = max_params.get("value", to_return[param])
+			if not is_interpolatable_type(min_value):
+				to_return[param] = max_value
+				continue
+			var elapsed := frame_index - frame_edges[0]
+			var delta = max_value - min_value
+			var duration := frame_edges[1] - frame_edges[0]
+			var trans_type: int = min_params.get("trans", Tween.TRANS_LINEAR)
+			if trans_type == Tween.TRANS_SPRING + 1:
+				to_return[param] = min_value
+				continue
+			var ease_type: Tween.EaseType = min_params.get("ease", Tween.EASE_IN)
+			to_return[param] = Tween.interpolate_value(
+				min_value, delta, elapsed, duration, trans_type, ease_type
+			)
+	return to_return
+
+
+func set_keyframe(
+	param_name: String,
+	frame_index: int,
+	value: Variant = params[param_name],
+	trans := Tween.TRANS_LINEAR,
+	ease_type := Tween.EASE_IN
+) -> void:
+	if not animated_params.has(param_name):
+		animated_params[param_name] = {}
+	var id := layer.next_keyframe_id
+	animated_params[param_name][frame_index] = {
+		"id": id, "value": value, "trans": trans, "ease": ease_type
+	}
+	layer.next_keyframe_id += 1
+	keyframe_set.emit()
+
+
+func is_interpolatable_type(value: Variant) -> bool:
+	var type := typeof(value)
+	match type:
+		TYPE_INT, TYPE_FLOAT, TYPE_VECTOR2, TYPE_VECTOR2I, TYPE_VECTOR3, TYPE_VECTOR3I:
+			return true
+		TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_COLOR, TYPE_QUATERNION:
+			return true
+		_:
+			return false
+
+
+func find_frame_edges(frame_index: int, animated_properties: Dictionary) -> Array[int]:
+	var param_keys := animated_properties.keys()
+	if param_keys.size() == 1:
+		return [param_keys[0], param_keys[0]]
+	param_keys.sort()
+	var minimum: int = param_keys[0]
+	var maximum: int = param_keys[-1]
+	for key in param_keys:
+		if key > minimum and key <= frame_index:
+			minimum = key
+		if key < maximum and key >= frame_index:
+			maximum = key
+	return [minimum, maximum]
+
+
 func serialize() -> Dictionary:
-	var p_str := {}
-	for param in params:
-		p_str[param] = var_to_str(params[param])
-	return {"name": name, "shader_path": shader.resource_path, "params": p_str, "enabled": enabled}
+	return {
+		"name": name,
+		"shader_path": shader.resource_path,
+		"enabled": enabled,
+		"params": var_to_str(params),
+		"animated_params": var_to_str(animated_params),
+	}
 
 
 func deserialize(dict: Dictionary) -> void:
@@ -34,12 +140,14 @@ func deserialize(dict: Dictionary) -> void:
 		var shader_to_load := load(path)
 		if is_instance_valid(shader_to_load) and shader_to_load is Shader:
 			shader = shader_to_load
+	if dict.has("enabled"):
+		enabled = dict["enabled"]
 	if dict.has("params"):
 		if typeof(dict["params"]) == TYPE_DICTIONARY:
 			for param in dict["params"]:
 				if typeof(dict["params"][param]) == TYPE_STRING:
 					params[param] = str_to_var(dict["params"][param])
 		else:
 			params = str_to_var(dict["params"])
-	if dict.has("enabled"):
-		enabled = dict["enabled"]
+	if dict.has("animated_params"):
+		animated_params = str_to_var(dict["animated_params"])

assets/graphics/timeline/keyframe_selected.svg.import

@@ -69,6 +69,7 @@ var ui_color := Color(0, 0, 0, 0):
 	set(value):
 		ui_color = value
 		ui_color_changed.emit()
+var next_keyframe_id := 0
 var text_server := TextServerManager.get_primary_interface()
 
 
@@ -255,13 +256,14 @@ func display_effects(cel: BaseCel, image_override: Image = null) -> Image:
 	if not effects_enabled:
 		return image
 	var image_size := image.get_size()
+	var frame := cel.get_frame(project)
+	var frame_index := project.frames.find(frame)
 	for effect in effects:
 		if not effect.enabled or not is_instance_valid(effect.shader):
 			continue
-		var params := effect.params
-		var frame := cel.get_frame(project)
+		var params := effect.get_params(frame_index)
 		params["PXO_time"] = frame.position_in_seconds(project)
-		params["PXO_frame_index"] = project.frames.find(frame)
+		params["PXO_frame_index"] = frame_index
 		params["PXO_layer_index"] = index
 		var shader_image_effect := ShaderImageEffect.new()
 		shader_image_effect.generate_image(image, effect.shader, params, image_size)
@@ -274,8 +276,12 @@ func display_effects(cel: BaseCel, image_override: Image = null) -> Image:
 		for effect in ancestor.effects:
 			if not effect.enabled:
 				continue
+			var params := effect.get_params(frame_index)
+			params["PXO_time"] = frame.position_in_seconds(project)
+			params["PXO_frame_index"] = frame_index
+			params["PXO_layer_index"] = index
 			var shader_image_effect := ShaderImageEffect.new()
-			shader_image_effect.generate_image(image, effect.shader, effect.params, image_size)
+			shader_image_effect.generate_image(image, effect.shader, params, image_size)
 	return image
 
 
@@ -312,7 +318,8 @@ func serialize() -> Dictionary:
 		"opacity": opacity,
 		"ui_color": ui_color,
 		"parent": parent.index if is_instance_valid(parent) else -1,
-		"effects": effect_data
+		"effects": effect_data,
+		"next_keyframe_id": next_keyframe_id,
 	}
 	if not user_data.is_empty():
 		dict["user_data"] = user_data
@@ -337,6 +344,7 @@ func deserialize(dict: Dictionary) -> void:
 	clipping_mask = dict.get("clipping_mask", false)
 	opacity = dict.get("opacity", 1.0)
 	user_data = dict.get("user_data", user_data)
+	next_keyframe_id = dict.get("next_keyframe_id", 0)
 	if dict.has("ui_color"):
 		var tmp_ui_color = dict.ui_color
 		if typeof(tmp_ui_color) == TYPE_STRING:
@@ -363,6 +371,7 @@ func deserialize(dict: Dictionary) -> void:
 				print("Loading effect failed, not a dictionary.")
 				continue
 			var effect := LayerEffect.new()
+			effect.layer = self
 			effect.deserialize(effect_dict)
 			effects.append(effect)
 

src/Classes/LayerEffect.gd

@@ -69,6 +69,7 @@ var global_layer_expand := true
 @onready var tag_container: Control = %TagContainer
 @onready var layer_frame_h_split := %LayerFrameHSplit as HSplitContainer
 @onready var layer_frame_header_h_split := %LayerFrameHeaderHSplit as HSplitContainer
+@onready var keyframe_timeline := %KeyframeTimeline as KeyframeTimeline
 @onready var delete_frame := %DeleteFrame as Button
 @onready var move_frame_left := %MoveFrameLeft as Button
 @onready var move_frame_right := %MoveFrameRight as Button
@@ -271,7 +272,7 @@ func reset_settings() -> void:
 func _get_minimum_size() -> Vector2:
 	# X targets enough to see layers, 1 frame, vertical scrollbar, and padding
 	# Y targets enough to see 1 layer
-	if not is_instance_valid(layer_vbox):
+	if not is_instance_valid(layer_vbox) or not cel_vbox.is_visible_in_tree():
 		return Vector2.ZERO
 	return Vector2(layer_vbox.size.x + cel_size + 26, cel_size + 105)
 
@@ -1798,3 +1799,10 @@ func _on_layer_frame_h_split_dragged(offset: int) -> void:
 		layer_frame_header_h_split.split_offset = offset
 	if layer_frame_h_split.split_offset != offset:
 		layer_frame_h_split.split_offset = offset
+
+
+func _on_keyframe_timeline_check_button_toggled(toggled_on: bool) -> void:
+	keyframe_timeline.visible = toggled_on
+	tag_scroll_container.visible = not toggled_on
+	layer_frame_header_h_split.get_parent().visible = not toggled_on
+	frame_scroll_container.get_parent().visible = not toggled_on