RNA

* Finished DNA_lamp_types.h, DNA_world_types.h and DNA_sound_types.h.
* Renamed "parent" struct property to "nested", and also remaining "from"
  usage to "base".
* Added a NEVER_NULL subtype for pointers and use it for all properties
  that apply.
* Make sure all structs have a description, and fix any other DOC_BROKEN
  descriptions, also many other naming consistency improvements.

1 files changed, 59 insertions, 59 deletions

diff --git a/source/blender/makesrna/intern/rna_sound.c b/source/blender/makesrna/intern/rna_sound.c
index 6a74a324232..60e7dd8dea2 100644
--- a/source/blender/makesrna/intern/rna_sound.c
+++ b/source/blender/makesrna/intern/rna_sound.c
@@ -36,6 +36,8 @@
 
 #else
 
+/* sample and listener are internal .. */
+
 #if 0
 static void rna_def_sample(BlenderRNA *brna)
 {
@@ -58,7 +60,7 @@ static void rna_def_sample(BlenderRNA *brna)
 	
 	srna= RNA_def_struct(brna, "SoundSample", "ID");
 	RNA_def_struct_sdna(srna, "bSample");
-	RNA_def_struct_ui_text(srna, "SoundSample", "Sound Sample");
+	RNA_def_struct_ui_text(srna, "SoundSample", "Sound data loaded from a sound datablock.");
 
 	prop= RNA_def_property(srna, "type", PROP_ENUM, PROP_NONE);
 	RNA_def_property_enum_items(prop, prop_sample_type_items);
@@ -87,7 +89,6 @@ static void rna_def_sample(BlenderRNA *brna)
 	RNA_def_property_ui_text(prop, "Channels", "Number of channels (mono=1; stereo=2)");
 	RNA_def_property_flag(prop, PROP_NOT_EDITABLE); 
 }
-#endif
 
 static void rna_def_soundlistener(BlenderRNA *brna)
 {
@@ -97,7 +98,7 @@ static void rna_def_soundlistener(BlenderRNA *brna)
 
 	srna= RNA_def_struct(brna, "SoundListener", "ID");
 	RNA_def_struct_sdna(srna, "bSoundListener");
-	RNA_def_struct_ui_text(srna, "Sound Listener", "DOC_BROKEN");
+	RNA_def_struct_ui_text(srna, "Sound Listener", "Sound listener defining paramaters about how sounds are played.");
 
 	prop= RNA_def_property(srna, "gain", PROP_FLOAT, PROP_NONE);
 	RNA_def_property_ui_text(prop, "Gain", "Overall volume for Game Engine sound.");
@@ -123,102 +124,101 @@ static void rna_def_soundlistener(BlenderRNA *brna)
 	RNA_def_property_ui_text(prop, "Total Sounds in Game Engine", "The total number of sounds in the Game Engine.");
 	RNA_def_property_flag(prop, PROP_NOT_EDITABLE);
 }
+#endif
 
 static void rna_def_sound(BlenderRNA *brna)
 {
-
 	StructRNA *srna;
 	PropertyRNA *prop;
 
 	srna= RNA_def_struct(brna, "Sound", "ID");
 	RNA_def_struct_sdna(srna, "bSound");
-	RNA_def_struct_ui_text(srna, "Sound", "DOC_BROKEN");
+	RNA_def_struct_ui_text(srna, "Sound", "Sound datablock referencing an external or packed sound file.");
 
-	prop= RNA_def_property(srna, "sample", PROP_POINTER, PROP_NONE);
-	RNA_def_property_struct_type(prop, "ID");
-	RNA_def_property_ui_text(prop, "Sample", "Sound Sample.");
+	rna_def_ipo_common(srna);
+
+	/*prop= RNA_def_property(srna, "sample", PROP_POINTER, PROP_NONE);
+	RNA_def_property_struct_type(prop, "SoundSample");
+	RNA_def_property_ui_text(prop, "Sample", "Sound sample.");*/
 
 	prop= RNA_def_property(srna, "filename", PROP_STRING, PROP_FILEPATH);
 	RNA_def_property_string_sdna(prop, NULL, "name");
-	RNA_def_property_flag(prop, PROP_NOT_EDITABLE); /* ? */
-	RNA_def_property_ui_text(prop, "Filename", "DOC_BROKEN");
+	RNA_def_property_ui_text(prop, "Filename", "Sound sample file used by this Sound datablock.");
+
+	prop= RNA_def_property(srna, "packed_file", PROP_POINTER, PROP_NONE);
+	RNA_def_property_pointer_sdna(prop, NULL, "packedfile");
+	RNA_def_property_ui_text(prop, "Packed File", "");
 
-	/* floats */
-	prop= RNA_def_property(srna, "volume", PROP_FLOAT, PROP_NONE);
+	/* game engine settings */
+	prop= RNA_def_property(srna, "volume", PROP_FLOAT, PROP_UNSIGNED);
 	RNA_def_property_float_sdna(prop, NULL, "volume");
-	RNA_def_property_ui_text(prop, "Volume", "The volume for this sound in the game engine only");
 	RNA_def_property_ui_range(prop, 0.0, 1.0, 10, 4);
-
-	prop= RNA_def_property(srna, "panning", PROP_FLOAT, PROP_NONE);
-	RNA_def_property_float_sdna(prop, NULL, "panning");
-	RNA_def_property_ui_text(prop, "Panning", "Pan the sound from left to right");
-	RNA_def_property_ui_range(prop, -1.0, 1.0, 10, 4); /* TODO - this isnt used anywhere :/ */
-
-	prop= RNA_def_property(srna, "attenuation", PROP_FLOAT, PROP_NONE);
-	RNA_def_property_float_sdna(prop, NULL, "attenuation");
-	RNA_def_property_ui_text(prop, "Attenuation", "DOC_BROKEN");
-	RNA_def_property_ui_range(prop, 0.0, 100.0, 10, 4); /* TODO check limits */
+	RNA_def_property_ui_text(prop, "Volume", "Game engine only: volume for this sound.");
 
 	prop= RNA_def_property(srna, "pitch", PROP_FLOAT, PROP_NONE);
 	RNA_def_property_float_sdna(prop, NULL, "pitch");
-	RNA_def_property_ui_text(prop, "Pitch", "Set the pitch of this sound for the game engine only");
 	RNA_def_property_ui_range(prop, -12.0, 12.0, 10, 4);
+	RNA_def_property_ui_text(prop, "Pitch", "Game engine only: set the pitch of this sound.");
+
+	prop= RNA_def_property(srna, "loop", PROP_BOOLEAN, PROP_NONE);
+	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_LOOP);
+	RNA_def_property_ui_text(prop, "Sound Loop", "Game engine only: toggle between looping on/off.");
 
+	prop= RNA_def_property(srna, "ping_pong", PROP_BOOLEAN, PROP_NONE);
+	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_BIDIRECTIONAL_LOOP);
+	RNA_def_property_ui_text(prop, "Ping Pong", "Game engine only: Toggle between A->B and A->B->A looping.");
+
+	prop= RNA_def_property(srna, "sound_3d", PROP_BOOLEAN, PROP_NONE);
+	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_3D);
+	RNA_def_property_ui_text(prop, "3D Sound", "Game engine only: turns 3D sound on.");
+
+	prop= RNA_def_property(srna, "attenuation", PROP_FLOAT, PROP_NONE);
+	RNA_def_property_float_sdna(prop, NULL, "attenuation");
+	RNA_def_property_range(prop, 0.0, 5.0);
+	RNA_def_property_ui_text(prop, "Attenuation", "Game engine only: sets the surround scaling factor for 3D sound.");
+
+	/* gain */
 	prop= RNA_def_property(srna, "min_gain", PROP_FLOAT, PROP_NONE);
 	RNA_def_property_float_sdna(prop, NULL, "min_gain");
-	RNA_def_property_ui_text(prop, "Min Gain", "DOC_BROKEN");
-	RNA_def_property_ui_range(prop, 0.0, 1.0, 10, 4); /* NOT used anywhere */
+	RNA_def_property_range(prop, 0.0, 1.0);
+	RNA_def_property_ui_text(prop, "Min Gain", "Minimal gain which is always guaranteed for this sound.");
 
 	prop= RNA_def_property(srna, "max_gain", PROP_FLOAT, PROP_NONE);
 	RNA_def_property_float_sdna(prop, NULL, "max_gain");
-	RNA_def_property_ui_text(prop, "Max Gain", "DOC_BROKEN");
-	RNA_def_property_ui_range(prop, 0.0, 1.0, 10, 4); /* NOT used anywhere */
+	RNA_def_property_range(prop, 0.0, 1.0);
+	RNA_def_property_ui_text(prop, "Max Gain", "Maximal gain which is always guaranteed for this sound.");
 
-	prop= RNA_def_property(srna, "distance", PROP_FLOAT, PROP_NONE);
+	prop= RNA_def_property(srna, "reference_distance", PROP_FLOAT, PROP_NONE);
 	RNA_def_property_float_sdna(prop, NULL, "distance");
-	RNA_def_property_ui_text(prop, "Distance", "Reference distance at which the listener will experience gain");
+	RNA_def_property_ui_text(prop, "Reference Distance", "Reference distance at which the listener will experience gain.");
 	RNA_def_property_ui_range(prop, 0.0, 1000.0, 10, 4); /* NOT used anywhere */
 
-	prop= RNA_def_property(srna, "ipo", PROP_POINTER, PROP_NONE);
-	RNA_def_property_struct_type(prop, "Ipo");
-	RNA_def_property_ui_text(prop, "Ipo", "DOC_BROKEN");
-
-
-	/* flags */
-	prop= RNA_def_property(srna, "loop", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_LOOP); /* use bitflags */
-	RNA_def_property_ui_text(prop, "Sound Loop", "DOC_BROKEN");
+	/* unused
+	prop= RNA_def_property(srna, "panning", PROP_FLOAT, PROP_NONE);
+	RNA_def_property_float_sdna(prop, NULL, "panning");
+	RNA_def_property_ui_range(prop, -1.0, 1.0, 10, 4);
+	RNA_def_property_ui_text(prop, "Panning", "Pan the sound from left to right"); */
 
+	/* unused
 	prop= RNA_def_property(srna, "fixed_volume", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_FIXED_VOLUME); /* use bitflags */
-	RNA_def_property_ui_text(prop, "Fixed Volume", "DOC_BROKEN");
+	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_FIXED_VOLUME);
+	RNA_def_property_ui_text(prop, "Fixed Volume", "Constraint sound to fixed volume."); */
 
+	/* unused
 	prop= RNA_def_property(srna, "fixed_panning", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_FIXED_PANNING); /* use bitflags */
-	RNA_def_property_ui_text(prop, "Fixed Panning", "DOC_BROKEN");
-
-	prop= RNA_def_property(srna, "spacial", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_3D); /* use bitflags */
-	RNA_def_property_ui_text(prop, "3D", "DOC_BROKEN");
-
-	prop= RNA_def_property(srna, "bidirectional_loop", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_BIDIRECTIONAL_LOOP); /* use bitflags */
-	RNA_def_property_ui_text(prop, "Bidirectional Loop", "DOC_BROKEN");
+	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_FIXED_PANNING);
+	RNA_def_property_ui_text(prop, "Fixed Panning", "Constraint sound to fixed panning."); */
 
+	/* unused
 	prop= RNA_def_property(srna, "priority", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_PRIORITY); /* use bitflags */
-	RNA_def_property_ui_text(prop, "Priority", "DOC_BROKEN");
-
-	prop= RNA_def_property(srna, "sequence", PROP_BOOLEAN, PROP_NONE);
-	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_SEQUENCE); /* use bitflags */
-	RNA_def_property_ui_text(prop, "Priority", "DOC_BROKEN");
-	RNA_def_property_flag(prop, PROP_NOT_EDITABLE);
+	RNA_def_property_boolean_sdna(prop, NULL, "flags", SOUND_FLAGS_PRIORITY);
+	RNA_def_property_ui_text(prop, "Priority", "Make sound higher priority."); */
 }
 
 void RNA_def_sound(BlenderRNA *brna)
 {
 	//rna_def_sample(brna);
-	rna_def_soundlistener(brna);
+	//rna_def_soundlistener(brna);
 	rna_def_sound(brna);
 }