Changeset 33147 in project


Ignore:
Timestamp:
01/28/16 09:52:27 (4 years ago)
Author:
John Croisant
Message:

sdl2: New color, point, and rect operations.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sdl2

    r33146 r33147  
    444444
    445445
     446
     447==== sdl2:color Operations
     448
    446449<setter>(color-set! color #!optional r g b a) → color</setter>
    447450<setter>(colour-set! color #!optional r g b a) → color</setter>
    448451
    449 Convenient way of setting multiple fields of the sdl2:color.
     452Efficient and convenient way of setting multiple fields of the sdl2:color.
    450453Any arguments that are {{#f}} will cause no change to that field.
    451454E.g. {{(color-set! my-color 42 #f 255 #f)}} will set the "r" field to 42 and the "b" field to 255, but will not change the "g" or "a" fields.
     
    473476
    474477
     478<procedure>(color-copy   src) → sdl2:color</procedure>
     479<procedure>(colour-copy  src) → sdl2:color</procedure>
    475480<procedure>(color-copy!  src dest) → dest</procedure>
    476481<procedure>(colour-copy! src dest) → dest</procedure>
    477 <procedure>(color-copy  src) → sdl2:color</procedure>
    478 <procedure>(colour-copy src) → sdl2:color</procedure>
     482
     483{{color-copy}} and {{colour-copy}} efficiently copy the values of {{src}} into a new managed sdl2:color.
     484{{color-copy}} and {{colour-copy}} are available in '''sdl2 egg version 0.2.0 and higher'''.
     485In earlier versions, they were named {{copy-color}} and {{copy-colour}}.
    479486
    480487{{color-copy!}} and {{colour-copy!}} efficiently copy the values of {{src}} into {{dest}},
    481488and return the modified {{dest}}.
    482 {{src}} and {{dest}} must both be sdl2:colors.
    483489It is safe (but useless) for {{src}} and {{dest}} to be the same object.
    484490{{color-copy!}} and {{colour-copy!}} are available in '''sdl2 egg version 0.2.0 and higher'''.
    485 
    486 {{color-copy}} and {{colour-copy}} efficiently copy the values of {{src}} into a new managed sdl2:color,
    487 and returns the new sdl2:color.
    488 They are equivalent to {{(color-copy! src (make-color))}}.
    489 {{color-copy}} and {{colour-copy}} are available in '''sdl2 egg version 0.2.0 and higher'''.
    490 In earlier versions, they were named {{copy-color}} and {{copy-colour}}.
    491491
    492492
     
    505505These procedures were deprecated in sdl2 egg version 0.2.0,
    506506and will be removed in a future version.
    507 
    508 If you need these procedures, you can implement them like so:
    509 
    510 <enscript highlight="scheme">
    511 (use (prefix sdl2 sdl2:))
    512 (define (copy-color* color)
    513   (sdl2:color-copy! color (sdl2:make-color*)))
    514 (define copy-colour* copy-color*)
    515 </enscript>
     507You can achieve the same effect using {{color-copy!}} and {{make-color*}}.
     508
     509
     510<procedure>(color-scale   color scale) → sdl2:color</procedure>
     511<procedure>(colour-scale  color scale) → sdl2:color</procedure>
     512<procedure>(color-scale!  color scale #!optional dest) → dest</procedure>
     513<procedure>(colour-scale! color scale #!optional dest) → dest</procedure>
     514
     515Efficiently scale (multiply) the RGBA values of {{color}} by {{scale}} (a float or integer).
     516E.g. {{scale}} 0.5 halves the RGBA values, {{scale}} 2.0 doubles the values.
     517
     518* {{color-scale}} and {{colour-scale}} return a new managed sdl2:color.
     519* {{color-scale!}} and {{colour-scale!}} modify and return {{dest}}.
     520  If {{dest}} is omitted, {{color}} is modified and returned.
     521
     522These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     523
     524The results are clamped to the range [0, 255].
     525sdl2:color can only hold integer values, so the results will be truncated to integers.
     526
     527
     528<procedure>(color-mult   color1 color2) → sdl2:color</procedure>
     529<procedure>(colour-mult  color1 color2) → sdl2:color</procedure>
     530<procedure>(color-mult!  color1 color2 #!optional dest) → dest</procedure>
     531<procedure>(colour-mult! color1 color2 #!optional dest) → dest</procedure>
     532
     533Efficiently multiply-blend {{color1}} by {{color2}}.
     534This is equivalent to the "multiply" blend mode of image editors,
     535where {{color1}} is the bottom layer and {{color2}} is the top layer.
     536
     537* {{color-mult}} and {{colour-mult}} return a new managed sdl2:color.
     538* {{color-mult!}} and {{colour-mult!}} modify and return {{dest}}.
     539  If {{dest}} is omitted, {{color1}} is modified and returned.
     540
     541These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     542
     543The results are clamped to the range [0, 255].
     544sdl2:color can only hold integer values, so the results will be truncated to integers.
     545
     546This operation only affects the R, G, and B values.
     547The result's A value will always be the same as {{color1}}'s A value.
     548
     549{{color2}}'s A value controls the strength of the effect.
     550E.g. 255 means full strength, 127 means half strength,
     5510 means no effect (the result will have the same values as {{color1}}).
     552
     553
     554<procedure>(color-add   color1 color2) → sdl2:color</procedure>
     555<procedure>(colour-add  color1 color2) → sdl2:color</procedure>
     556<procedure>(color-add!  color1 color2 #!optional dest) → dest</procedure>
     557<procedure>(colour-add! color1 color2 #!optional dest) → dest</procedure>
     558
     559Efficiently add-blend {{color1}} by {{color2}}.
     560This is equivalent to the "addition" blend mode of image editors,
     561where {{color1}} is the bottom layer and {{color2}} is the top layer.
     562
     563* {{color-add}} and {{colour-add}} return a new managed sdl2:color.
     564* {{color-add!}} and {{colour-add!}} modify and return {{dest}}.
     565  If {{dest}} is omitted, {{color1}} is modified and returned.
     566
     567These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     568
     569The results are clamped to the range [0, 255].
     570sdl2:color can only hold integer values, so the results will be truncated to integers.
     571
     572This operation only affects the R, G, and B values.
     573The result's A value will always be the same as {{color1}}'s A value.
     574
     575{{color2}}'s A value controls the strength of the effect.
     576E.g. 255 means full strength, 127 means half strength,
     5770 means no effect (the result will have the same values as {{color1}}).
     578
     579
     580<procedure>(color-sub! color1 color2 #!optional dest) → dest</procedure>
     581<procedure>(colour-sub! color1 color2 #!optional dest) → dest</procedure>
     582
     583Efficiently subtract-blend {{color1}} by {{color2}}.
     584This is equivalent to the "subtract" blend mode of image editors,
     585where {{color1}} is the bottom layer and {{color2}} is the top layer.
     586
     587* {{color-sub}} and {{colour-sub}} return a new managed sdl2:color.
     588* {{color-sub!}} and {{colour-sub!}} modify and return {{dest}}.
     589  If {{dest}} is omitted, {{color1}} is modified and returned.
     590
     591These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     592
     593The results are clamped to the range [0, 255].
     594sdl2:color can only hold integer values, so the results will be truncated to integers.
     595
     596This operation only affects the R, G, and B values.
     597The result's A value will always be the same as {{color1}}'s A value.
     598
     599{{color2}}'s A value controls the strength of the effect.
     600E.g. 255 means full strength, 127 means half strength,
     6010 means no effect (the result will have the same values as {{color1}}).
    516602
    517603
     
    31713257
    31723258
     3259
     3260==== sdl2:rect Operations
     3261
    31733262<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
    31743263
    3175 Convenient way of setting multiple fields of the sdl2:rect.
     3264Efficient and convenient way of setting multiple fields of the sdl2:rect.
    31763265Any arguments that are {{#f}} will cause no change to that field.
    31773266E.g. {{(rect-set! my-rect 42 #f 1337 #f)}} will set the "x" field to 42 and the "w" field to 1337, but will not change the "y" or "h" fields.
     
    31973286
    31983287
     3288<procedure>(rect-copy src) → sdl2:rect</procedure>
    31993289<procedure>(rect-copy! src dest) → dest</procedure>
    3200 <procedure>(rect-copy src) → sdl2:rect</procedure>
     3290
     3291{{rect-copy}} efficiently copies the values of {{src}} into a new managed sdl2:rect.
     3292{{rect-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
     3293In earlier versions, it was named {{copy-rect}}.
    32013294
    32023295{{rect-copy!}} efficiently copies the values of {{src}} into {{dest}},
    32033296and returns the modified {{dest}}.
    3204 {{src}} and {{dest}} must both be sdl2:rects.
    32053297It is safe (but useless) for {{src}} and {{dest}} to be the same object.
    32063298{{rect-copy!}} is available in '''sdl2 egg version 0.2.0 and higher'''.
    3207 
    3208 {{rect-copy}} efficiently copies the values of {{src}} into a new managed sdl2:rect,
    3209 and returns the new sdl2:rect.
    3210 It is equivalent to {{(rect-copy! src (make-rect))}}.
    3211 {{rect-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
    3212 In earlier versions, it was named {{copy-rect}}.
    32133299
    32143300
     
    32253311This procedure was deprecated in sdl2 egg version 0.2.0,
    32263312and will be removed in a future version.
    3227 
    3228 If you need this procedure, you can implement it like so:
    3229 
    3230 <enscript highlight="scheme">
    3231 (use (prefix sdl2 sdl2:))
    3232 (define (copy-rect* rect)
    3233   (sdl2:rect-copy! rect (sdl2:make-rect*)))
    3234 </enscript>
     3313You can achieve the same effect using {{rect-copy!}} and {{make-rect*}}.
     3314
     3315
     3316<procedure>(rect-scale  rect scale) → sdl2:rect</procedure>
     3317<procedure>(rect-scale! rect scale #!optional dest) → dest</procedure>
     3318
     3319Efficiently scale (multiply) the X, Y, W, and H values of {{rect}} by {{scale}} (a float or integer).
     3320E.g. {{scale}} 0.5 halves the values, {{scale}} 2.0 doubles the values.
     3321sdl2:rect can only hold integer values, so the results will be truncated to integers.
     3322
     3323* {{rect-scale}} returns a new managed sdl2:rect.
     3324* {{rect-scale!}} modifies and returns {{dest}}.
     3325  If {{dest}} is omitted, {{rect}} is modified and returned.
     3326
     3327These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3328
     3329'''WARNING:''' sdl2:rect can only hold values in the range -2147483648 to 2147483647.
     3330The behavior of these procedures is not specified if any result would be outside of that range.
     3331
     3332
     3333<procedure>(rect-move  rect dx dy) → sdl2:rect</procedure>
     3334<procedure>(rect-move! rect dx dy #!optional dest) → dest</procedure>
     3335
     3336Efficiently move {{rect}} by adding the given amounts to its X and Y values.
     3337{{dx}} and {{dy}} must be integers.
     3338
     3339If {{dx}} and {{dy}} are already stored in an sdl2:point,
     3340it is more efficient and convenient to use {{rect-add-point}} or {{rect-sub-point}},
     3341instead of extracting the individual fields from the point.
     3342
     3343* {{rect-move}} returns a new managed sdl2:rect.
     3344* {{rect-move!}} modifies and returns {{dest}}.
     3345  If {{dest}} is omitted, {{rect}} is modified and returned.
     3346
     3347These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3348
     3349'''WARNING:''' sdl2:rect can only hold values in the range -2147483648 to 2147483647.
     3350The behavior of these procedures is not specified if any result would be outside of that range.
     3351
     3352
     3353<procedure>(rect-add-point  rect point) → sdl2:rect</procedure>
     3354<procedure>(rect-add-point! rect point #!optional dest) → dest</procedure>
     3355
     3356Efficiently move {{rect}} by adding {{point}} to {{rect}}'s X and Y values.
     3357
     3358If the dx and dy values are already held as separate variables,
     3359it is more efficient and convenient to use {{rect-move}},
     3360instead of creating an sdl2:point.
     3361
     3362* {{rect-add-point}} returns a new managed sdl2:rect.
     3363* {{rect-add-point!}} modifies and returns {{dest}}.
     3364  If {{dest}} is omitted, {{rect}} is modified and returned.
     3365
     3366These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3367
     3368'''WARNING:''' sdl2:rect can only hold values in the range -2147483648 to 2147483647.
     3369The behavior of these procedures is not specified if any result would be outside of that range.
     3370
     3371
     3372<procedure>(rect-sub-point  rect point) → sdl2:rect</procedure>
     3373<procedure>(rect-sub-point! rect point #!optional dest) → dest</procedure>
     3374
     3375Efficiently move {{rect}} by subtracting {{point}} from {{rect}}'s X and Y values.
     3376
     3377If the dx and dy values are already held as separate variables,
     3378it is more efficient and convenient to negate the values and use {{rect-move}},
     3379instead of creating an sdl2:point.
     3380
     3381* {{rect-sub-point}} returns a new managed sdl2:rect.
     3382* {{rect-sub-point!}} modifies and returns {{dest}}.
     3383  If {{dest}} is omitted, {{rect}} is modified and returned.
     3384
     3385These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3386
     3387'''WARNING:''' sdl2:rect can only hold values in the range -2147483648 to 2147483647.
     3388The behavior of these procedures is not specified if any result would be outside of that range.
     3389
     3390
     3391<procedure>(rect-grow  rect dw dh) → sdl2:rect</procedure>
     3392<procedure>(rect-grow! rect dw dh #!optional dest) → dest</procedure>
     3393
     3394Efficiently increase {{rect}}'s size by adding to its W and H values.
     3395The rect's top left corner will stay the same.
     3396See also {{rect-grow/center!}}, which keeps the rect's center point the same.
     3397
     3398{{dw}} and {{dh}} must be integers.
     3399Negative numbers cause the size to decrease (i.e. shrink).
     3400
     3401* {{rect-grow}} returns a new managed sdl2:rect.
     3402* {{rect-grow!}} modifies and returns {{dest}}.
     3403  If {{dest}} is omitted, {{rect}} is modified and returned.
     3404
     3405These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3406
     3407'''WARNING:''' sdl2:rect can only hold values in the range -2147483648 to 2147483647.
     3408The behavior of these procedures is not specified if any result would be outside of that range.
     3409
     3410
     3411<procedure>(rect-grow/center  rect dw dh) → sdl2:rect</procedure>
     3412<procedure>(rect-grow/center! rect dw dh #!optional dest) → dest</procedure>
     3413
     3414Efficiently increase {{rect}}'s size while trying to keep the same center point.
     3415See also {{rect-grow!}}, which keeps the rect's top left corner the same.
     3416
     3417{{dw}} and {{dh}} must be integers.
     3418Negative numbers cause the size to decrease (i.e. shrink).
     3419
     3420For best results, use even numbers for {{dw}} and {{dh}}.
     3421If {{dw}} or {{dh}} are odd numbers, the rect's center point will change by half a pixel due to rounding.
     3422
     3423* {{rect-grow/center}} returns a new managed sdl2:rect.
     3424* {{rect-grow/center!}} modifies and returns {{dest}}.
     3425  If {{dest}} is omitted, {{rect}} is modified and returned.
     3426
     3427These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3428
     3429'''WARNING:''' sdl2:rect can only hold values in the range -2147483648 to 2147483647.
     3430The behavior of these procedures is not specified if any result would be outside of that range.
    32353431
    32363432
     
    32813477
    32823478
     3479
     3480==== sdl2:point Operations
     3481
    32833482<procedure>(point-set! point #!optional x y) → point</procedure>
    32843483
    3285 Convenient way of setting multiple fields of the sdl2:point.
     3484Efficient and convenient way of setting multiple fields of the sdl2:point.
    32863485Any arguments that are {{#f}} will cause no change to that field.
    32873486E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field.
     
    33063505
    33073506
     3507<procedure>(point-copy src) → sdl2:point</procedure>
    33083508<procedure>(point-copy! src dest) → dest</procedure>
    3309 <procedure>(point-copy src) → sdl2:point</procedure>
     3509
     3510{{point-copy}} efficiently copies the values of {{src}} into a new managed sdl2:point.
     3511{{point-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
     3512In earlier versions, it was named {{copy-point}}.
    33103513
    33113514{{point-copy!}} efficiently copies the values of {{src}} into {{dest}},
    33123515and returns the modified {{dest}}.
    3313 {{src}} and {{dest}} must both be sdl2:points.
    33143516It is safe (but useless) for {{src}} and {{dest}} to be the same object.
    33153517{{point-copy!}} is available in '''sdl2 egg version 0.2.0 and higher'''.
    3316 
    3317 {{point-copy}} efficiently copies the values of {{src}} into a new managed sdl2:point,
    3318 and returns the new sdl2:point.
    3319 It is equivalent to {{(point-copy! src (make-point))}}.
    3320 {{point-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
    3321 In earlier versions, it was named {{copy-point}}.
    33223518
    33233519
     
    33343530This procedure was deprecated in sdl2 egg version 0.2.0,
    33353531and will be removed in a future version.
    3336 
    3337 If you need this procedure, you can implement it like so:
    3338 
    3339 <enscript highlight="scheme">
    3340 (use (prefix sdl2 sdl2:))
    3341 (define (copy-point* point)
    3342   (sdl2:point-copy! point (sdl2:make-point*)))
    3343 </enscript>
     3532You can achieve the same effect using {{point-copy!}} and {{make-point*}}.
     3533
     3534
     3535<procedure>(point-scale  point scale) → sdl2:point</procedure>
     3536<procedure>(point-scale! point scale #!optional dest) → dest</procedure>
     3537
     3538Efficiently scale (multiply) the X and Y values of {{point}} by {{scale}} (a float or integer).
     3539E.g. {{scale}} 0.5 halves the values, {{scale}} 2.0 doubles the values.
     3540sdl2:point can only hold integer values, so the results will be truncated to integers.
     3541
     3542These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3543
     3544* {{point-scale}} returns a new managed sdl2:point.
     3545* {{point-scale!}} modifies and returns {{dest}}.
     3546  If {{dest}} is omitted, {{point}} is modified and returned.
     3547
     3548'''WARNING:''' sdl2:point can only hold values in the range -2147483648 to 2147483647.
     3549The behavior of these procedures is not specified if any result would be outside of that range.
     3550
     3551
     3552<procedure>(point-move  point dx dy) → sdl2:point</procedure>
     3553<procedure>(point-move! point dx dy #!optional dest) → dest</procedure>
     3554
     3555Efficiently move {{point}} by adding the given amounts to its X and Y values.
     3556{{dx}} and {{dy}} must be integers.
     3557
     3558If {{dx}} and {{dy}} are already stored in an sdl2:point,
     3559it is more efficient and convenient to use {{point-add}} or {{point-sub}},
     3560instead of extracting the individual fields from the point.
     3561
     3562* {{point-move}} returns a new managed sdl2:point.
     3563* {{point-move!}} modifies and returns {{dest}}.
     3564  If {{dest}} is omitted, {{point}} is modified and returned.
     3565
     3566These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3567
     3568'''WARNING:''' sdl2:point can only hold values in the range -2147483648 to 2147483647.
     3569The behavior of these procedures is not specified if any result would be outside of that range.
     3570
     3571
     3572<procedure>(point-add  point1 point2) → sdl2:point</procedure>
     3573<procedure>(point-add! point1 point2 #!optional dest) → dest</procedure>
     3574
     3575Efficiently add {{point1}} and {{point2}} (vector addition).
     3576
     3577If the dx and dy values are already held as separate variables,
     3578it is more efficient and convenient to use {{point-move}},
     3579instead of creating an sdl2:point.
     3580
     3581* {{point-add}} returns a new managed sdl2:point.
     3582* {{point-add!}} modifies and returns {{dest}}.
     3583  If {{dest}} is omitted, {{point1}} is modified and returned.
     3584
     3585These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3586
     3587'''WARNING:''' sdl2:point can only hold values in the range -2147483648 to 2147483647.
     3588The behavior of these procedures is not specified if any result would be outside of that range.
     3589
     3590
     3591<procedure>(point-sub  point1 point2) → sdl2:point</procedure>
     3592<procedure>(point-sub! point1 point2 #!optional dest) → dest</procedure>
     3593
     3594Efficiently subtract {{point2}} from {{point1}} (vector subtraction).
     3595
     3596If the dx and dy values are already held as separate variables instead,
     3597it is more efficient and convenient to negate the values and use {{point-move}},
     3598instead of creating an sdl2:point.
     3599
     3600* {{point-sub}} returns a new managed sdl2:point.
     3601* {{point-sub!}} modifies and returns {{dest}}.
     3602  If {{dest}} is omitted, {{point1}} is modified and returned.
     3603
     3604These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     3605
     3606'''WARNING:''' sdl2:point can only hold values in the range -2147483648 to 2147483647.
     3607The behavior of these procedures is not specified if any result would be outside of that range.
    33443608
    33453609
Note: See TracChangeset for help on using the changeset viewer.